@indigoai-us/hq-cli 5.108.0 → 5.108.2

package/dist/lib/mesh/client.js

@@ -0,0 +1,268 @@
+/**
+ * Shared work-mesh transport client.
+ * Existing `hq mesh` verbs and work-context reconcile both use this for
+ * vault HTTP + receipt-shaped responses (US-007A / US-007B).
+ */
+import { listActiveMembershipCompanies, meshJson, requireToken, resolveMeshCompany, } from "./api.js";
+export { meshJson, requireToken, resolveMeshCompany, listActiveMembershipCompanies };
+export async function openMeshTransport(opts) {
+    const token = await requireToken();
+    const company = await resolveMeshCompany(token, opts.company);
+    return { token, company };
+}
+/**
+ * POST work-session registration for a queued outbox operation.
+ * Maps HTTP status to retryable vs quarantine.
+ */
+export function createWorkSessionDeliverer(opts) {
+    return async (op) => {
+        const companyUid = op.companyUid;
+        if (!companyUid) {
+            return { ok: false, retryable: false, code: "COMPANY_UID_REQUIRED" };
+        }
+        const body = {
+            contractVersion: 1,
+            companyUid,
+            sessionId: op.sessionId,
+            clientOperationId: op.clientOperationId,
+            operationId: op.operationId,
+            digest: op.digest,
+            contextStatus: op.projectId && op.taskId ? "bound" : op.projectId ? "needs_task" : "unresolved",
+        };
+        if (op.projectId)
+            body.projectId = op.projectId;
+        if (op.taskId)
+            body.taskId = op.taskId;
+        try {
+            if (opts.post) {
+                const res = await opts.post("/v1/work-mesh/work-sessions", body);
+                return mapRegisterResponse(res.status, res.body, op.operationId);
+            }
+            const data = await meshJson(opts.token, "/v1/work-mesh/work-sessions", {
+                method: "POST",
+                body,
+            });
+            return mapRegisterResponse(200, data, op.operationId);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // meshJson throws on !ok with error text; classify roughly.
+            if (/^401\b|^403\b|unauthorized|forbidden|auth/i.test(message)) {
+                return { ok: false, retryable: false, code: "AUTH_DENIED" };
+            }
+            if (/^400\b|^422\b|invalid|validation/i.test(message)) {
+                return { ok: false, retryable: false, code: "VALIDATION_FAILED" };
+            }
+            if (/^5\d\d\b|ECONN|ENOTFOUND|ETIMEDOUT|network|fetch failed/i.test(message)) {
+                return { ok: false, retryable: true, code: "NETWORK_OR_5XX" };
+            }
+            // Unknown: keep queued (fail open to retry, not quarantine).
+            return { ok: false, retryable: true, code: "TRANSPORT_ERROR" };
+        }
+    };
+}
+function mapRegisterResponse(status, body, operationId) {
+    if (status >= 200 && status < 300) {
+        const rec = body && typeof body === "object" ? body : {};
+        const receiptId = (typeof rec.receiptId === "string" && rec.receiptId) ||
+            (typeof rec.bindingEpisodeId === "string" && rec.bindingEpisodeId) ||
+            (typeof rec.operationId === "string" && rec.operationId) ||
+            operationId;
+        return { ok: true, receiptId };
+    }
+    if (status >= 500 || status === 429) {
+        return { ok: false, retryable: true, code: `HTTP_${status}` };
+    }
+    if (status === 401 || status === 403 || status === 400 || status === 422) {
+        return { ok: false, retryable: false, code: `HTTP_${status}` };
+    }
+    if (status === 0) {
+        return { ok: false, retryable: true, code: "NETWORK_UNAVAILABLE" };
+    }
+    return { ok: false, retryable: true, code: `HTTP_${status}` };
+}
+/**
+ * Probe whether the server advertises migration capability (US-017A).
+ * Failures return false (default-company stays locked).
+ */
+export async function fetchMigrationCapability(token, companyUid) {
+    try {
+        const data = (await meshJson(token, "/v1/work-mesh/capabilities", {
+            query: { companyUid },
+        }));
+        return Boolean(data.migration || data.migrationCapability);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Unlock rule for default-company mode (US-017B): migration must be true for
+ * EVERY company the caller belongs to. Offline / empty memberships → locked.
+ */
+export async function probeMigrationCapabilityForMemberships(token, opts) {
+    const now = (opts?.now ?? (() => new Date()))().toISOString();
+    const list = opts?.listCompanies ?? listActiveMembershipCompanies;
+    const fetchOne = opts?.fetchOne ?? fetchMigrationCapability;
+    let companies;
+    try {
+        companies = await list(token);
+    }
+    catch {
+        return { unlocked: false, offline: true, checkedAt: now, companies: [] };
+    }
+    if (companies.length === 0) {
+        return { unlocked: false, offline: false, checkedAt: now, companies: [] };
+    }
+    const results = [];
+    for (const c of companies) {
+        const migration = await fetchOne(token, c.companyUid);
+        results.push({
+            companyUid: c.companyUid,
+            companySlug: c.companySlug,
+            migration,
+        });
+    }
+    return {
+        unlocked: results.every((r) => r.migration),
+        offline: false,
+        checkedAt: now,
+        companies: results,
+    };
+}
+/**
+ * POST /v1/work-mesh/sessions/{sessionId}/migrate
+ */
+export function createMigratePoster(opts) {
+    return async (input) => {
+        const path = `/v1/work-mesh/sessions/${encodeURIComponent(input.sessionId)}/migrate`;
+        const body = {
+            operationId: input.operationId,
+            digest: input.digest,
+            sourceCompanyUid: input.sourceCompanyUid,
+            destinationCompanyUid: input.destinationCompanyUid,
+            destination: input.destination,
+            expectedVersion: input.expectedVersion,
+        };
+        let status;
+        let data;
+        if (opts.post) {
+            const res = await opts.post(path, body);
+            status = res.status;
+            data = res.body;
+        }
+        else {
+            data = await meshJson(opts.token, path, { method: "POST", body });
+            status = 201;
+        }
+        if (status < 200 || status >= 300) {
+            const err = data && typeof data === "object" ? data : {};
+            const code = typeof err.code === "string" ? err.code : `HTTP_${status}`;
+            const message = typeof err.error === "string"
+                ? err.error
+                : typeof err.message === "string"
+                    ? err.message
+                    : code;
+            throw new Error(`${code}: ${message}`);
+        }
+        const rec = data;
+        if (!rec?.receipt?.operationId || !rec.destinationCompanyUid) {
+            throw new Error("RECEIPT_INCOMPLETE: migrate response missing receipt");
+        }
+        return rec;
+    };
+}
+/**
+ * GET /v1/work-mesh/sessions/{sessionId}/candidates?companyUid=...
+ */
+export function createCandidatesFetcher(opts) {
+    return async ({ sessionId, companyUid }) => {
+        const path = `/v1/work-mesh/sessions/${encodeURIComponent(sessionId)}/candidates`;
+        const data = opts.get
+            ? await opts.get(path, { companyUid })
+            : await meshJson(opts.token, path, { query: { companyUid } });
+        return data;
+    };
+}
+/**
+ * POST /v1/work-mesh/sessions/{sessionId}/organize
+ */
+export function createOrganizePoster(opts) {
+    return async (input) => {
+        const path = `/v1/work-mesh/sessions/${encodeURIComponent(input.sessionId)}/organize`;
+        const body = {
+            companyUid: input.companyUid,
+            operationId: input.operationId,
+            digest: input.digest,
+            decision: input.decision,
+            expectedVersion: input.expectedVersion,
+        };
+        if (input.decisionExpiresAt) {
+            body.decisionExpiresAt = input.decisionExpiresAt;
+        }
+        let status;
+        let data;
+        if (opts.post) {
+            const res = await opts.post(path, body);
+            status = res.status;
+            data = res.body;
+        }
+        else {
+            data = await meshJson(opts.token, path, { method: "POST", body });
+            status = 201;
+        }
+        if (status < 200 || status >= 300) {
+            const err = data && typeof data === "object" ? data : {};
+            const code = typeof err.code === "string" ? err.code : `HTTP_${status}`;
+            const message = typeof err.error === "string"
+                ? err.error
+                : typeof err.message === "string"
+                    ? err.message
+                    : code;
+            throw new Error(`${code}: ${message}`);
+        }
+        const rec = data;
+        if (!rec?.receipt?.operationId || !rec.projectId || !rec.bindingEpisodeId) {
+            throw new Error("RECEIPT_INCOMPLETE: organize response missing receipt");
+        }
+        return rec;
+    };
+}
+/** GET /v1/work-mesh/live?companyUid=... */
+export async function fetchCompanyLive(token, companyUid, opts) {
+    const query = { companyUid };
+    if (opts?.cursor)
+        query.cursor = opts.cursor;
+    const data = opts?.get
+        ? await opts.get("/v1/work-mesh/live", query)
+        : await meshJson(token, "/v1/work-mesh/live", { query });
+    return data;
+}
+export function formatCompanyLiveTable(live, companyLabel) {
+    const lines = [
+        `Work mesh live: ${companyLabel}  generatedAt=${live.generatedAt}`,
+        "actorUid\tpresence\tdisplayName\tsessionId\tstatus\tcontext\tproject\ttask\tturns",
+    ];
+    for (const p of live.participants ?? []) {
+        const sessions = p.sessions ?? [];
+        if (sessions.length === 0) {
+            lines.push(`${p.actorUid}\t${p.presence ?? "?"}\t${p.displayName ?? ""}\t-\t-\t-\t-\t-\t-`);
+            continue;
+        }
+        for (const s of sessions) {
+            lines.push([
+                p.actorUid,
+                p.presence ?? "?",
+                p.displayName ?? "",
+                s.sessionId,
+                s.status ?? "?",
+                s.contextStatus ?? "?",
+                s.projectId ?? "",
+                s.taskId ?? "",
+                String(s.turnCount ?? 0),
+            ].join("\t"));
+        }
+    }
+    return lines;
+}
+//# sourceMappingURL=client.js.map

package/dist/lib/mesh/live/backoff.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Full-jitter exponential backoff (base 1s, cap 60s).
+ * sleep = random_uniform(0, min(cap, base * 2^attempt))
+ */
+export declare const BACKOFF_BASE_MS = 1000;
+export declare const BACKOFF_CAP_MS = 60000;
+export declare const FLUSH_MAX_ATTEMPTS = 5;
+export type RandomFn = () => number;
+export type SleepFn = (ms: number) => Promise<void>;
+export declare function fullJitterDelayMs(attempt: number, opts?: {
+    baseMs?: number;
+    capMs?: number;
+    random?: RandomFn;
+}): number;
+export declare function defaultSleep(ms: number): Promise<void>;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/lib/mesh/live/backoff.js

@@ -0,0 +1,20 @@
+/**
+ * Full-jitter exponential backoff (base 1s, cap 60s).
+ * sleep = random_uniform(0, min(cap, base * 2^attempt))
+ */
+export const BACKOFF_BASE_MS = 1000;
+export const BACKOFF_CAP_MS = 60_000;
+export const FLUSH_MAX_ATTEMPTS = 5;
+export function fullJitterDelayMs(attempt, opts = {}) {
+    const base = opts.baseMs ?? BACKOFF_BASE_MS;
+    const cap = opts.capMs ?? BACKOFF_CAP_MS;
+    const random = opts.random ?? Math.random;
+    const exp = Math.min(cap, base * 2 ** attempt);
+    return Math.floor(random() * exp);
+}
+export async function defaultSleep(ms) {
+    if (ms <= 0)
+        return;
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=backoff.js.map

package/dist/lib/mesh/live/daemon/board-refresh.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Refresh ~/.hq/work-context/sessions/<sid>/board.md for bound sessions
+ * from GET /companies/{companyUid}/board at most every 60s.
+ * Metadata-only snapshot — never prompts or tokens.
+ */
+export declare const BOARD_REFRESH_INTERVAL_MS = 60000;
+export interface BoardStorySnapshot {
+    id: string;
+    title?: string;
+    status?: string;
+}
+export interface BoardReader {
+    (companyUid: string, projectId: string): Promise<{
+        projectId: string;
+        projectName?: string;
+        stories: BoardStorySnapshot[];
+    } | null>;
+}
+export interface BoardRefreshDeps {
+    workContextRoot: string;
+    readBoard: BoardReader;
+    now?: () => number;
+    /** Per-session last refresh timestamps (ms). */
+    lastRefresh?: Map<string, number>;
+    intervalMs?: number;
+}
+export declare function formatBoardMarkdown(input: {
+    sessionId: string;
+    companyUid: string;
+    projectId: string;
+    projectName?: string;
+    taskId?: string;
+    stories: BoardStorySnapshot[];
+    refreshedAt: string;
+}): string;
+export declare function writeBoardMarkdown(workContextRoot: string, sessionId: string, markdown: string): string;
+/**
+ * Refresh board.md for bound sessions whose last refresh is older than interval.
+ */
+export declare function refreshBoundSessionBoards(deps: BoardRefreshDeps): Promise<{
+    refreshed: number;
+    skipped: number;
+    errors: number;
+}>;
+/** Build a BoardReader from meshJson-compatible fetch. */
+export declare function createVaultBoardReader(opts: {
+    getJson: (path: string) => Promise<unknown>;
+}): BoardReader;
+//# sourceMappingURL=board-refresh.d.ts.map

package/dist/lib/mesh/live/daemon/board-refresh.js

@@ -0,0 +1,185 @@
+/**
+ * Refresh ~/.hq/work-context/sessions/<sid>/board.md for bound sessions
+ * from GET /companies/{companyUid}/board at most every 60s.
+ * Metadata-only snapshot — never prompts or tokens.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { workContextSessionsDir } from "../../../work-context/paths.js";
+import { readSessionState } from "../../../work-context/state.js";
+import { sessionBoardPath } from "./paths.js";
+export const BOARD_REFRESH_INTERVAL_MS = 60_000;
+function listBoundSessionIds(workContextRoot) {
+    const dir = workContextSessionsDir(workContextRoot);
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        const sid = name.slice(0, -".json".length);
+        const state = readSessionState(sid, workContextRoot);
+        if (state?.contextStatus === "bound" && state.companyUid && state.projectId) {
+            out.push(sid);
+        }
+    }
+    return out;
+}
+export function formatBoardMarkdown(input) {
+    const lines = [
+        `# Board snapshot`,
+        ``,
+        `- sessionId: ${input.sessionId}`,
+        `- companyUid: ${input.companyUid}`,
+        `- projectId: ${input.projectId}`,
+    ];
+    if (input.projectName)
+        lines.push(`- projectName: ${input.projectName}`);
+    if (input.taskId)
+        lines.push(`- taskId: ${input.taskId}`);
+    lines.push(`- refreshedAt: ${input.refreshedAt}`, ``, `## Stories`, ``);
+    if (input.stories.length === 0) {
+        lines.push(`_(no stories)_`, ``);
+    }
+    else {
+        for (const s of input.stories.slice(0, 50)) {
+            const title = s.title ? ` — ${s.title}` : "";
+            const status = s.status ? ` [${s.status}]` : "";
+            lines.push(`- ${s.id}${status}${title}`);
+        }
+        lines.push(``);
+    }
+    return lines.join("\n");
+}
+export function writeBoardMarkdown(workContextRoot, sessionId, markdown) {
+    const dest = sessionBoardPath(workContextRoot, sessionId);
+    fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+    const tmp = `${dest}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, markdown, { mode: 0o600 });
+    fs.renameSync(tmp, dest);
+    try {
+        fs.chmodSync(dest, 0o600);
+    }
+    catch {
+        /* best-effort */
+    }
+    return dest;
+}
+/**
+ * Refresh board.md for bound sessions whose last refresh is older than interval.
+ */
+export async function refreshBoundSessionBoards(deps) {
+    const now = deps.now ?? Date.now;
+    const interval = deps.intervalMs ?? BOARD_REFRESH_INTERVAL_MS;
+    const last = deps.lastRefresh ?? new Map();
+    let refreshed = 0;
+    let skipped = 0;
+    let errors = 0;
+    for (const sessionId of listBoundSessionIds(deps.workContextRoot)) {
+        const prev = last.get(sessionId);
+        if (prev !== undefined && now() - prev < interval) {
+            skipped += 1;
+            continue;
+        }
+        const state = readSessionState(sessionId, deps.workContextRoot);
+        if (!state ||
+            state.contextStatus !== "bound" ||
+            !state.companyUid ||
+            !state.projectId) {
+            skipped += 1;
+            continue;
+        }
+        try {
+            const board = await deps.readBoard(state.companyUid, state.projectId);
+            if (!board) {
+                skipped += 1;
+                last.set(sessionId, now());
+                continue;
+            }
+            const md = formatBoardMarkdown({
+                sessionId,
+                companyUid: state.companyUid,
+                projectId: state.projectId,
+                projectName: board.projectName,
+                taskId: state.taskId,
+                stories: board.stories,
+                refreshedAt: new Date(now()).toISOString(),
+            });
+            writeBoardMarkdown(deps.workContextRoot, sessionId, md);
+            last.set(sessionId, now());
+            refreshed += 1;
+        }
+        catch {
+            errors += 1;
+        }
+    }
+    return { refreshed, skipped, errors };
+}
+/** Build a BoardReader from meshJson-compatible fetch. */
+export function createVaultBoardReader(opts) {
+    return async (companyUid, projectId) => {
+        const raw = await opts.getJson(`/companies/${encodeURIComponent(companyUid)}/board`);
+        if (!raw || typeof raw !== "object")
+            return null;
+        const rec = raw;
+        const projects = Array.isArray(rec.projects)
+            ? rec.projects
+            : Array.isArray(rec.board) &&
+                typeof rec.board[0] === "object"
+                ? rec.board
+                : [];
+        // Also accept ACL-scoped model: { projects: [...] } or nested board.projects
+        const nested = rec.board && typeof rec.board === "object" && !Array.isArray(rec.board)
+            ? rec.board.projects
+            : undefined;
+        const list = Array.isArray(nested) ? nested : projects;
+        for (const item of list) {
+            if (!item || typeof item !== "object" || Array.isArray(item))
+                continue;
+            const p = item;
+            const id = typeof p.id === "string" ? p.id : typeof p.projectId === "string" ? p.projectId : "";
+            if (id !== projectId)
+                continue;
+            const storiesRaw = Array.isArray(p.stories)
+                ? p.stories
+                : Array.isArray(p.tasks)
+                    ? p.tasks
+                    : [];
+            const stories = [];
+            for (const s of storiesRaw) {
+                if (!s || typeof s !== "object" || Array.isArray(s))
+                    continue;
+                const row = s;
+                const sid = typeof row.id === "string"
+                    ? row.id
+                    : typeof row.storyId === "string"
+                        ? row.storyId
+                        : typeof row.taskId === "string"
+                            ? row.taskId
+                            : "";
+                if (!sid)
+                    continue;
+                stories.push({
+                    id: sid,
+                    title: typeof row.title === "string"
+                        ? row.title.slice(0, 120)
+                        : typeof row.name === "string"
+                            ? row.name.slice(0, 120)
+                            : undefined,
+                    status: typeof row.status === "string" ? row.status : undefined,
+                });
+            }
+            return {
+                projectId,
+                projectName: typeof p.name === "string"
+                    ? p.name
+                    : typeof p.title === "string"
+                        ? p.title
+                        : undefined,
+                stories,
+            };
+        }
+        return { projectId, stories: [] };
+    };
+}
+//# sourceMappingURL=board-refresh.js.map

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

@@ -0,0 +1,71 @@
+/**
+ * Contract-3 realtime credential vend + 80%-of-lifetime renewal.
+ * Never logs or persists credential material.
+ */
+import type { IotCredentials } from "./presign.js";
+export declare const REALTIME_CREDENTIALS_PATH = "/v1/realtime/credentials";
+export declare const MQTT_KEEPALIVE_SECONDS = 15;
+/** Renew at 80% of credential lifetime. */
+export declare const CREDENTIAL_RENEWAL_FRACTION = 0.8;
+export declare const MIN_RENEWAL_DELAY_MS = 5000;
+export interface PresenceCompany {
+    companyUid: string;
+    presenceTopic: string;
+}
+export interface Contract3Bundle {
+    contractVersion: 3;
+    credentials: IotCredentials;
+    iotEndpoint: string;
+    region: string;
+    clientId: string;
+    actorUid: string;
+    actorType: "human" | "agent";
+    companies: PresenceCompany[];
+    droppedCompanies: string[];
+    expiresAt: string;
+}
+export type CredentialsFetcher = () => Promise<Contract3Bundle>;
+export interface TimerHost {
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    now(): number;
+}
+export declare const realTimerHost: TimerHost;
+export declare function renewalDelayMs(nowMs: number, expirationIso: string): number;
+export declare function normalizeContract3Bundle(raw: unknown): Contract3Bundle;
+/**
+ * When `HQ_AGENT_IDENTITY_FILE` names a companyUid, keep only that company
+ * from the vend (must be present) and refuse every other company. Presence
+ * and session events then attribute to the box agent for its company only.
+ * No identity file → return the bundle unchanged (person laptop).
+ */
+export declare function scopeBundleToAgentIdentity(bundle: Contract3Bundle, env?: NodeJS.ProcessEnv): Contract3Bundle;
+export declare function createContract3Fetcher(opts: {
+    token: string;
+    baseUrl?: string;
+    post?: (path: string, body: unknown) => Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    /** Process env for identity-file scoping (tests). */
+    env?: NodeJS.ProcessEnv;
+}): CredentialsFetcher;
+/**
+ * Proactive renewal: at 80% of lifetime, fetch fresh creds and call onRenewed.
+ * Does not drop the connection itself — caller reconnects with the new URL.
+ */
+export declare class CredentialRenewalManager {
+    private readonly fetchCredentials;
+    private readonly onRenewed;
+    private readonly onError;
+    private readonly timers;
+    private readonly retryDelayMs;
+    private handle;
+    private stopped;
+    constructor(fetchCredentials: CredentialsFetcher, onRenewed: (bundle: Contract3Bundle) => void, onError?: (err: unknown) => void, timers?: TimerHost, retryDelayMs?: number);
+    schedule(bundle: Contract3Bundle): void;
+    private renew;
+    stop(): void;
+    private clear;
+}
+//# sourceMappingURL=credentials.d.ts.map