@indigoai-us/hq-cli 5.101.5 → 5.101.7

package/dist/commands/outposts-heartbeat.js

@@ -1,188 +0,0 @@
-/**
- * `hq outposts heartbeat` — publish this box's agent-session summary to the
- * realtime fabric.
- *
- * Runs ON an Outpost, under systemd. It enumerates the box's local Claude Code
- * and Codex sessions with cheap scandir + stat + bounded reads, projects them
- * down to the compact secret-free `AgentSession[]` payload, and publishes to
- * `hq/{personUid}/sessions` so Mission Control can see what the box is doing.
- *
- * ## Why the cadence lives in here
- *
- * The original box-side design was a bash `while` loop that, every 5 seconds,
- * ran `hq auth refresh` and then `npx -y --package=@indigoai-us/hq-cloud@latest
- * outpost-session-heartbeat-runner`. That is ~35k process launches a day, and
- * every `npx` re-resolves the package and re-reads it off disk — on a t3 box
- * whose EBS budget is the scarce resource, that is a meaningful, permanent tax
- * for a job that should be nearly free.
- *
- * So the loop lives in-process instead:
- *   - identity is resolved ONCE per process, not once per tick;
- *   - the Cognito session refreshes itself on demand (`ensureCognitoToken`
- *     returns the cached token until it is close to expiry), so there is no
- *     separate per-tick `hq auth refresh`;
- *   - the IoT client is cached across ticks by the publisher and only rebuilt
- *     when its credentials near expiry.
- *
- * The loop is deliberately unkillable-by-transients: a failed publish, a failed
- * enumeration, or a not-yet-warm session are all logged and retried on the next
- * tick. Nothing here should ever take the service down, because a service that
- * exits looks identical to a service that is quietly failing.
- */
-import { mkdir, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { DEFAULT_VAULT_API_URL } from "../utils/cognito-session.js";
-import { resolveCallerPersonUid } from "../utils/vault-api.js";
-import { DEFAULT_HEARTBEAT_INTERVAL_SECONDS, collectSessions, nodeFileSystem, sessionsTopicForPerson, } from "../outpost/session-heartbeat.js";
-import { createIotPublishPort, defaultRealtimeCredentialsFetcher, } from "../outpost/session-heartbeat-publisher.js";
-/**
- * Resolve the cadence from the flag, then the environment, then the default.
- * Floored at 1s: a sub-second cadence hammers the fabric for no benefit, and a
- * zero/negative value would spin the loop hot.
- */
-export function resolveIntervalSeconds(flag, env = process.env) {
-    for (const raw of [flag, env.OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS]) {
-        if (raw === undefined || raw === null || raw === "")
-            continue;
-        const parsed = Number.parseInt(raw, 10);
-        if (!Number.isFinite(parsed))
-            return DEFAULT_HEARTBEAT_INTERVAL_SECONDS;
-        return Math.max(1, parsed);
-    }
-    return DEFAULT_HEARTBEAT_INTERVAL_SECONDS;
-}
-/**
- * Where the box records its last LANDED heartbeat. The post-provision audit
- * reads this file's freshness, because "systemd says the unit is active" is not
- * evidence that anything was published — that gap is what let a heartbeat fail
- * every five seconds for nine days while every dashboard stayed green.
- *
- * Lives under the service user's home so the unit (User=ec2-user) can write it
- * without extra tmpfiles.d wiring; the SSM collector reads it as root.
- */
-export const DEFAULT_HEARTBEAT_STATE_FILE = join(homedir(), ".hq", "outpost-session-heartbeat.json");
-/** Persist the liveness marker the box audit reads. */
-export async function writeHeartbeatState(path, payload) {
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, `${JSON.stringify({
-        lastPublishAt: payload.emittedAt,
-        sessions: payload.sessions.length,
-    })}\n`, "utf8");
-}
-/** Structured one-line log — journald gets JSON, not prose. */
-function logLine(step, outcome, extra, now) {
-    return JSON.stringify({
-        service: "outpost-session-heartbeat",
-        step,
-        outcome,
-        ...extra,
-        timestamp: now().toISOString(),
-    });
-}
-/**
- * Run the heartbeat loop. Returns the number of ticks performed.
- *
- * A "tick" is one attempt, whether or not it published — the count is the
- * loop's liveness, not its success rate.
- */
-export async function runHeartbeatLoop(options, deps) {
-    const intervalMs = (options.intervalSeconds ?? DEFAULT_HEARTBEAT_INTERVAL_SECONDS) * 1000;
-    const maxTicks = options.once ? 1 : options.maxTicks;
-    // Resolved once and reused. Re-resolving per tick was the original sin.
-    let personUid = null;
-    let ticks = 0;
-    for (;;) {
-        ticks += 1;
-        try {
-            if (!personUid)
-                personUid = await deps.getPersonUid();
-            const payload = await collectSessions({ personUid, home: options.home, now: deps.now }, { fs: deps.fs });
-            const topic = sessionsTopicForPerson(personUid);
-            await deps.publish(topic, payload);
-            // Ordering matters: the marker is written only once the publish has
-            // resolved, so a stale marker means "nothing landed", not "nothing ran".
-            await deps.onPublished?.(payload);
-            if (options.json)
-                deps.log(JSON.stringify(payload));
-            deps.log(logLine("publish", "ok", { topic, sessions: payload.sessions.length }, deps.now));
-        }
-        catch (err) {
-            // Every failure mode lands here on purpose: a transient must never take
-            // the service down, because systemd restarting a hot-failing loop looks
-            // exactly like a healthy one.
-            deps.log(logLine("tick", "error", { message: err instanceof Error ? err.message : String(err) }, deps.now));
-        }
-        if (options.once)
-            break;
-        if (maxTicks !== undefined && ticks >= maxTicks)
-            break;
-        if (options.signal?.aborted)
-            break;
-        await deps.sleep(intervalMs, options.signal);
-        if (options.signal?.aborted)
-            break;
-    }
-    return ticks;
-}
-/** Wire the production dependencies and register the subcommand. */
-export function registerHeartbeatCommand(outposts) {
-    outposts
-        .command("heartbeat", { hidden: true })
-        .description("Publish this box's agent-session summary to the realtime fabric (runs on the Outpost, under systemd)")
-        .option("--once", "Emit a single heartbeat and exit")
-        .option("--interval <seconds>", "Cadence in seconds (default 5; env OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS)")
-        .option("--home <path>", "Home directory to scan for sessions")
-        .option("--api-base-url <url>", "HQ API base URL")
-        .option("--state-file <path>", `Liveness marker read by the box audit (default ${DEFAULT_HEARTBEAT_STATE_FILE})`)
-        .option("--json", "Print each published payload as JSON")
-        .action(async (opts) => {
-        const apiBaseUrl = opts.apiBaseUrl ??
-            process.env.HQAPI_BASE_URL ??
-            DEFAULT_VAULT_API_URL;
-        const getJwt = () => ensureCognitoToken({ interactive: false });
-        const deps = {
-            fs: nodeFileSystem,
-            publish: createIotPublishPort({
-                fetchCredentials: defaultRealtimeCredentialsFetcher({
-                    apiBaseUrl,
-                    getJwt,
-                }),
-            }),
-            // Same base as the credentials fetch. Resolving identity against the
-            // default plane while vending credentials from another sends a
-            // deployment-specific token to the wrong control plane, which is
-            // rejected — and the loop then retries forever without publishing.
-            getPersonUid: async () => resolveCallerPersonUid(await getJwt(), apiBaseUrl),
-            sleep: (ms, signal) => new Promise((resolve) => {
-                if (signal?.aborted)
-                    return resolve();
-                const t = setTimeout(done, ms);
-                function done() {
-                    clearTimeout(t);
-                    signal?.removeEventListener("abort", done);
-                    resolve();
-                }
-                signal?.addEventListener("abort", done, { once: true });
-            }),
-            now: () => new Date(),
-            log: (line) => console.error(line),
-            onPublished: (payload) => writeHeartbeatState(opts.stateFile ?? DEFAULT_HEARTBEAT_STATE_FILE, payload),
-        };
-        // systemd sends SIGTERM on stop/restart — finish the in-flight tick,
-        // then exit cleanly rather than being killed mid-publish.
-        const controller = new AbortController();
-        const stop = () => controller.abort();
-        process.once("SIGTERM", stop);
-        process.once("SIGINT", stop);
-        await runHeartbeatLoop({
-            once: opts.once,
-            intervalSeconds: resolveIntervalSeconds(opts.interval),
-            home: opts.home,
-            json: opts.json,
-            signal: controller.signal,
-        }, deps);
-    });
-}
-//# sourceMappingURL=outposts-heartbeat.js.map

package/dist/outpost/session-heartbeat-publisher.d.ts

@@ -1,76 +0,0 @@
-/**
- * Outpost on-box realtime publisher — mission-control US-009.
- *
- * The box already holds a Cognito session (seeded from the caller's refresh
- * token in user-data, kept fresh by the box's auth timers — see provision.ts).
- * This module turns that session into a `PublishPort` for the session-heartbeat
- * emitter using the EXACT on-box credential pattern the rest of the realtime
- * fabric uses (docs/realtime-fabric.md):
- *
- *   1. POST {HQAPI}/v1/realtime/credentials with the box's Cognito JWT.
- *      The Lambda resolves the caller's `personUid` from the verified JWT
- *      (never request input) and vends short-lived STS creds whose session
- *      policy scopes `iot:Connect/Publish/...` to `hq/{personUid}/*` only.
- *   2. SigV4-sign an IoT Data-plane publish with those creds to
- *      `hq/{personUid}/sessions`.
- *
- * No new auth surface, no embedded long-lived key, no per-device cert — the
- * per-identity STS session policy is the isolation boundary (US-010).
- *
- * The HTTP fetch + IoT client are injected so this is unit-testable without a
- * live endpoint; `defaultRealtimeCredentialsFetcher` and the IoT publish are
- * the production wiring.
- */
-import { IoTDataPlaneClient } from "@aws-sdk/client-iot-data-plane";
-import type { PublishPort } from "./session-heartbeat.js";
-import { sessionsTopicForPerson } from "./session-heartbeat.js";
-/** Shape returned by `POST /v1/realtime/credentials` (mirrors the handler). */
-export interface RealtimeCredentialsResponse {
-    credentials: {
-        accessKeyId: string;
-        secretAccessKey: string;
-        sessionToken: string;
-        expiration: string;
-    };
-    iotEndpoint: string;
-    region: string;
-    /** The caller's own topic — `hq/{personUid}/...`. */
-    topic: string;
-    expiresAt: string;
-}
-/** Fetches scoped realtime credentials for the box. Injected for tests. */
-export type RealtimeCredentialsFetcher = () => Promise<RealtimeCredentialsResponse>;
-/** Ceiling on a single credentials request. */
-export declare const DEFAULT_CREDENTIALS_TIMEOUT_MS = 10000;
-/**
- * Build the production credentials fetcher. Reads the box's current Cognito
- * id/access token via the injected `getJwt` and POSTs it to the
- * realtime-credentials endpoint.
- */
-export declare function defaultRealtimeCredentialsFetcher(opts: {
-    apiBaseUrl: string;
-    getJwt: () => Promise<string>;
-    fetchImpl?: typeof fetch;
-    /** Bound the request. Defaults to {@link DEFAULT_CREDENTIALS_TIMEOUT_MS}. */
-    timeoutMs?: number;
-}): RealtimeCredentialsFetcher;
-/**
- * Create a `PublishPort` that vends scoped creds (refreshing before expiry) and
- * publishes the compact payload to the box's own sessions topic over MQTT/IoT.
- *
- * @param fetchCredentials  vends per-identity-scoped STS creds + IoT endpoint
- * @param makeClient        builds an IoT client from creds (injected for tests)
- * @param now               clock injection
- */
-export declare function createIotPublishPort(opts: {
-    fetchCredentials: RealtimeCredentialsFetcher;
-    makeClient?: (args: {
-        endpoint: string;
-        region: string;
-        credentials: RealtimeCredentialsResponse["credentials"];
-    }) => IoTDataPlaneClient;
-    now?: () => Date;
-}): PublishPort;
-/** Re-export for the runner so it imports one module. */
-export { sessionsTopicForPerson };
-//# sourceMappingURL=session-heartbeat-publisher.d.ts.map

package/dist/outpost/session-heartbeat-publisher.js

@@ -1,117 +0,0 @@
-/**
- * Outpost on-box realtime publisher — mission-control US-009.
- *
- * The box already holds a Cognito session (seeded from the caller's refresh
- * token in user-data, kept fresh by the box's auth timers — see provision.ts).
- * This module turns that session into a `PublishPort` for the session-heartbeat
- * emitter using the EXACT on-box credential pattern the rest of the realtime
- * fabric uses (docs/realtime-fabric.md):
- *
- *   1. POST {HQAPI}/v1/realtime/credentials with the box's Cognito JWT.
- *      The Lambda resolves the caller's `personUid` from the verified JWT
- *      (never request input) and vends short-lived STS creds whose session
- *      policy scopes `iot:Connect/Publish/...` to `hq/{personUid}/*` only.
- *   2. SigV4-sign an IoT Data-plane publish with those creds to
- *      `hq/{personUid}/sessions`.
- *
- * No new auth surface, no embedded long-lived key, no per-device cert — the
- * per-identity STS session policy is the isolation boundary (US-010).
- *
- * The HTTP fetch + IoT client are injected so this is unit-testable without a
- * live endpoint; `defaultRealtimeCredentialsFetcher` and the IoT publish are
- * the production wiring.
- */
-import { IoTDataPlaneClient, PublishCommand, } from "@aws-sdk/client-iot-data-plane";
-import { assertNoSecretsInPayload, sessionsTopicForPerson, } from "./session-heartbeat.js";
-/** Ceiling on a single credentials request. */
-export const DEFAULT_CREDENTIALS_TIMEOUT_MS = 10_000;
-/**
- * Build the production credentials fetcher. Reads the box's current Cognito
- * id/access token via the injected `getJwt` and POSTs it to the
- * realtime-credentials endpoint.
- */
-export function defaultRealtimeCredentialsFetcher(opts) {
-    const doFetch = opts.fetchImpl ?? fetch;
-    return async () => {
-        const jwt = await opts.getJwt();
-        const res = await doFetch(`${opts.apiBaseUrl}/v1/realtime/credentials`, {
-            method: "POST",
-            // Bounded. An endpoint that accepts the connection but never answers
-            // would otherwise park the tick forever: the loop stops beating, the
-            // liveness marker goes stale, and SIGTERM cannot finish the in-flight
-            // tick — a hang that reads exactly like a healthy quiet box.
-            signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_CREDENTIALS_TIMEOUT_MS),
-            headers: {
-                authorization: `Bearer ${jwt}`,
-                "content-type": "application/json",
-            },
-        });
-        if (!res.ok) {
-            throw new Error(`realtime/credentials returned ${res.status} ${res.statusText}`);
-        }
-        return (await res.json());
-    };
-}
-/**
- * Create a `PublishPort` that vends scoped creds (refreshing before expiry) and
- * publishes the compact payload to the box's own sessions topic over MQTT/IoT.
- *
- * @param fetchCredentials  vends per-identity-scoped STS creds + IoT endpoint
- * @param makeClient        builds an IoT client from creds (injected for tests)
- * @param now               clock injection
- */
-export function createIotPublishPort(opts) {
-    const now = opts.now ?? (() => new Date());
-    const makeClient = opts.makeClient ??
-        (({ endpoint, region, credentials }) => {
-            const url = endpoint.startsWith("http")
-                ? endpoint
-                : `https://${endpoint}`;
-            return new IoTDataPlaneClient({
-                endpoint: url,
-                region,
-                credentials: {
-                    accessKeyId: credentials.accessKeyId,
-                    secretAccessKey: credentials.secretAccessKey,
-                    sessionToken: credentials.sessionToken,
-                },
-            });
-        });
-    let cached = null;
-    // Refresh creds this many ms before they actually expire so a publish never
-    // races expiry mid-flight.
-    const REFRESH_SKEW_MS = 60_000;
-    async function clientFor() {
-        const nowMs = now().getTime();
-        if (cached && cached.expiresAtMs - REFRESH_SKEW_MS > nowMs) {
-            return { client: cached.client };
-        }
-        const vended = await opts.fetchCredentials();
-        const client = makeClient({
-            endpoint: vended.iotEndpoint,
-            region: vended.region,
-            credentials: vended.credentials,
-        });
-        cached = {
-            client,
-            endpoint: vended.iotEndpoint,
-            accessKeyId: vended.credentials.accessKeyId,
-            expiresAtMs: Date.parse(vended.credentials.expiration),
-        };
-        return { client };
-    }
-    return async (topic, payload) => {
-        // Re-guard at the transport boundary — a publisher must never ship a
-        // payload that fails the no-secrets contract, regardless of caller.
-        assertNoSecretsInPayload(payload);
-        const { client } = await clientFor();
-        await client.send(new PublishCommand({
-            topic,
-            qos: 0,
-            payload: Buffer.from(JSON.stringify(payload)),
-        }));
-    };
-}
-/** Re-export for the runner so it imports one module. */
-export { sessionsTopicForPerson };
-//# sourceMappingURL=session-heartbeat-publisher.js.map

package/dist/outpost/session-heartbeat.d.ts

@@ -1,210 +0,0 @@
-/**
- * Outpost on-box session heartbeat emitter — mission-control US-009.
- *
- * Runs ON the Outpost VM (not in a Lambda). On a fixed cadence it:
- *   1. enumerates the box's local Claude Code (`~/.claude/projects/**\/<uuid>.jsonl`)
- *      and Codex (`~/.codex/session_index.jsonl` + `sessions/YYYY/MM/DD/rollout-*.jsonl`)
- *      sessions using cheap scandir + stat + BOUNDED tail/head reads only —
- *      it NEVER full-parses a multi-MB transcript;
- *   2. summarizes them into a compact `AgentSession[]` payload with
- *      `origin="outpost"`, mirroring the local reader logic from US-002/US-003;
- *   3. publishes that payload to the realtime fabric topic `hq/{personUid}/sessions`
- *      using the same on-box credential pattern the rest of the box uses
- *      (a server-minted, per-identity-scoped STS session vended by
- *      `POST /v1/realtime/credentials`, then an MQTT-over-WSS publish).
- *
- * Security (US-009 acceptance): the payload carries ONLY the AgentSession
- * fields below — never a transcript body, prompt, token, API key, env var, or
- * credential. `assertNoSecretsInPayload` is the runtime guard, and the unit
- * tests assert the no-secrets-in-payload guarantee against adversarial
- * fixtures.
- *
- * This module is intentionally dependency-light and pure-logic where it can be:
- * the filesystem, clock, and publish transport are all injected so the
- * enumeration → payload mapping and the no-secrets guarantee are unit-testable
- * without a real VM, real MQTT, or real STS.
- */
-/** Which agent tool produced the session. */
-export type AgentTool = "claude" | "codex";
-/** Where the session physically lives. The outpost emitter always emits `outpost`. */
-export type AgentOrigin = "local" | "outpost";
-/**
- * Session liveness taxonomy (US-001). Derived best-effort from a last-activity
- * mtime window. `awaiting_input` is not inferable from on-disk artifacts alone
- * on the box, so the emitter only ever produces `running | idle | ended`; the
- * desktop merges/cross-checks and may surface `awaiting_input` for local PIDs.
- */
-export type AgentStatus = "running" | "awaiting_input" | "idle" | "ended";
-/**
- * Unified, compact agent session summary. This is the ONLY shape that crosses
- * the wire — no transcript bodies, no secrets. Matches the Rust struct +
- * TS type defined in the hq-sync repo (US-001).
- */
-export interface AgentSession {
-    /** Stable session id (the `<uuid>` for Claude, the rollout/index id for Codex). */
-    id: string;
-    tool: AgentTool;
-    origin: AgentOrigin;
-    /** Working directory the session is running in, if known. */
-    cwd: string | null;
-    /** Project slug/name (last path segment of cwd, or decoded Claude project dir). */
-    project: string | null;
-    /** Owning company slug, if resolvable from HQ workspace metadata. */
-    company: string | null;
-    /** Model id last seen for the session, if observed in a bounded read. */
-    model: string | null;
-    status: AgentStatus;
-    /** ISO-8601 first-seen / creation time, if known. */
-    startedAt: string | null;
-    /** ISO-8601 last-activity time (file mtime is the liveness signal). */
-    lastActivityAt: string | null;
-    /** Provenance of this record — the on-box file we summarized. Path only, never content. */
-    source: string;
-}
-/** Liveness thresholds (seconds). Mirrors the desktop liveness engine (US-004). */
-export interface LivenessThresholds {
-    /** ≤ this since last activity ⇒ `running`. */
-    runningWithinSeconds: number;
-    /** ≤ this (and > running) ⇒ `idle`; beyond ⇒ `ended`. */
-    idleWithinSeconds: number;
-}
-/**
- * Default cadence matches the desktop polling interval (~5s). Configurable via
- * the `OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS` env var so dev/staging can
- * dial it without a rebuild — read by `resolveCadenceSeconds`.
- */
-export declare const DEFAULT_HEARTBEAT_INTERVAL_SECONDS = 5;
-/**
- * Default liveness windows. `running` ⇐ activity within the last 2 cadence
- * ticks (10s); `idle` out to 15m; older ⇒ `ended`. Kept generous so a session
- * mid-think between writes isn't flapped to `ended`.
- */
-export declare const DEFAULT_LIVENESS_THRESHOLDS: LivenessThresholds;
-/** A directory entry as returned by the filesystem port. */
-export interface DirEntry {
-    name: string;
-    isDirectory: boolean;
-    isFile: boolean;
-}
-/** Minimal stat surface used by the enumerator. */
-export interface FileStat {
-    /** Last-modification time, ms since epoch. */
-    mtimeMs: number;
-    /** Birth/creation time, ms since epoch (may equal mtime on filesystems w/o btime). */
-    birthtimeMs: number;
-    size: number;
-}
-/**
- * Filesystem port — abstracts node:fs so tests drive an in-memory tree and the
- * real emitter uses `nodeFileSystem`. Every read here is bounded.
- */
-export interface FileSystemPort {
-    /** Returns [] when the dir is missing — enumeration must not throw on absence. */
-    readDir(path: string): Promise<DirEntry[]>;
-    stat(path: string): Promise<FileStat>;
-    /** Whole-file read — used ONLY for the tiny Codex index, never for transcripts. */
-    readTextFile(path: string): Promise<string>;
-    /**
-     * Bounded read: at most `maxBytes` from the END of the file (tail) or the
-     * START (head). Implementations MUST NOT load the whole file. Returns "" on
-     * any error (missing/locked) — enumeration is best-effort.
-     */
-    readBounded(path: string, maxBytes: number, from: "head" | "tail"): Promise<string>;
-}
-/** Publishes the compact payload to the realtime topic. Injected for tests. */
-export type PublishPort = (topic: string, payload: SessionsHeartbeatPayload) => Promise<void>;
-/** The full envelope published to `hq/{personUid}/sessions`. */
-export interface SessionsHeartbeatPayload {
-    /** Schema discriminator for the desktop subscriber. */
-    type: "sessions";
-    /** Always `outpost` from this emitter. */
-    origin: "outpost";
-    /** ISO-8601 emit time. */
-    emittedAt: string;
-    /** The compact session summaries — live only, newest first, size-bounded. */
-    sessions: AgentSession[];
-    /**
-     * How many sessions the box actually has on disk, including the `ended`
-     * archive that is deliberately not published. Present so a consumer can tell
-     * "this box has 15 sessions" from "this box has 9,340 and we sent the live
-     * 15" — a filtered list that looks complete is worse than no list.
-     */
-    totalSessions?: number;
-    /** True when the byte budget forced sessions to be dropped. */
-    truncated?: boolean;
-}
-/**
- * Serialized-payload ceiling, in bytes.
- *
- * AWS IoT Core hard-rejects publishes over 128 KiB (131,072) — the box's first
- * real heartbeat died on exactly that. This budget sits under it with headroom
- * for the envelope and for any field a future schema adds.
- */
-export declare const IOT_PAYLOAD_BUDGET_BYTES: number;
-export interface HeartbeatConfig {
-    /** Caller's canonical HQ person id (`prs_*`). Topic = `hq/{personUid}/sessions`. */
-    personUid: string;
-    /** Home directory to scan (defaults to the process HOME). */
-    home?: string;
-    /** Liveness thresholds (defaults to {@link DEFAULT_LIVENESS_THRESHOLDS}). */
-    thresholds?: LivenessThresholds;
-    /** Clock injection for deterministic tests. */
-    now?: () => Date;
-}
-export interface HeartbeatDeps {
-    fs: FileSystemPort;
-    publish: PublishPort;
-}
-/** The sessions topic for a person. `hq/{personUid}/sessions`. */
-export declare function sessionsTopicForPerson(personUid: string): string;
-/** Resolve the heartbeat cadence (seconds) from env, clamped to a sane floor. */
-export declare function resolveCadenceSeconds(env?: NodeJS.ProcessEnv): number;
-/**
- * Map an mtime to a status given the thresholds and `now`. On the box we have
- * no per-session PID cross-check (that's the desktop's job), so we only emit
- * `running | idle | ended` — the desktop refines from there.
- */
-export declare function deriveStatus(lastActivityMs: number, nowMs: number, thresholds?: LivenessThresholds): AgentStatus;
-/** Decode Claude's `-`-joined project dir back to a best-effort cwd. */
-export declare function decodeClaudeProjectDir(dirName: string): string;
-interface CodexIndexRecord {
-    id: string;
-    cwd: string | null;
-    model: string | null;
-    timestamp: string | null;
-    /** Relative path under ~/.codex, when the index records it. */
-    path: string | null;
-}
-/** Parse the small newline-delimited Codex index into records. */
-export declare function parseCodexIndex(text: string): CodexIndexRecord[];
-/**
- * Project an arbitrary session-like object down to EXACTLY the whitelisted
- * AgentSession fields. Any extra key (e.g. a transcript snippet, token, env
- * var) is dropped here — this is the structural half of the no-secrets
- * guarantee.
- */
-export declare function toCompactSession(s: AgentSession): AgentSession;
-/**
- * Runtime guard: throw if the payload carries any non-whitelisted key OR any
- * value that looks like a secret. The behavioral half of the no-secrets
- * guarantee — defense in depth on top of `toCompactSession`. Called before
- * every publish.
- */
-export declare function assertNoSecretsInPayload(payload: SessionsHeartbeatPayload): void;
-/**
- * Enumerate the box's Claude + Codex sessions and build the compact,
- * secret-free payload. Pure w.r.t. the injected fs/clock — does NOT publish.
- */
-export declare function collectSessions(config: HeartbeatConfig, deps: Pick<HeartbeatDeps, "fs">): Promise<SessionsHeartbeatPayload>;
-/**
- * One heartbeat tick: collect → guard → publish to `hq/{personUid}/sessions`.
- * Best-effort and non-fatal by contract — a publish failure must not crash the
- * box's heartbeat loop (the desktop falls back to the S3-vault heartbeat /
- * stale-timeout, US-011). Returns the payload that was published (or attempted)
- * so callers/tests can assert on it; re-throws nothing.
- */
-export declare function emitHeartbeatOnce(config: HeartbeatConfig, deps: HeartbeatDeps): Promise<SessionsHeartbeatPayload>;
-/** Production FileSystemPort backed by node:fs with bounded positioned reads. */
-export declare const nodeFileSystem: FileSystemPort;
-export {};
-//# sourceMappingURL=session-heartbeat.d.ts.map