@indigoai-us/hq-cli 5.77.12 → 5.77.13

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

@@ -0,0 +1,210 @@
+/**
+ * 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