@indigoai-us/hq-cloud 6.15.4 → 6.15.6

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

@@ -0,0 +1,117 @@
+/**
+ * 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/outposts/session-heartbeat-publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-heartbeat-publisher.js","sourceRoot":"","sources":["../../src/outposts/session-heartbeat-publisher.ts"],"names":[],"mappings":"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"}

package/dist/outposts/session-heartbeat-publisher.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tests for the on-box realtime publisher (mission-control US-009):
+ *   - defaultRealtimeCredentialsFetcher POSTs the box's JWT to
+ *     /v1/realtime/credentials and parses the response
+ *   - createIotPublishPort vends scoped creds, builds an IoT client, publishes
+ *     to the caller's topic, caches the client until near-expiry, and re-guards
+ *     the no-secrets contract at the transport boundary
+ */
+export {};
+//# sourceMappingURL=session-heartbeat-publisher.test.d.ts.map

package/dist/outposts/session-heartbeat-publisher.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-heartbeat-publisher.test.d.ts","sourceRoot":"","sources":["../../src/outposts/session-heartbeat-publisher.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/outposts/session-heartbeat-publisher.test.js

@@ -0,0 +1,153 @@
+/**
+ * Tests for the on-box realtime publisher (mission-control US-009):
+ *   - defaultRealtimeCredentialsFetcher POSTs the box's JWT to
+ *     /v1/realtime/credentials and parses the response
+ *   - createIotPublishPort vends scoped creds, builds an IoT client, publishes
+ *     to the caller's topic, caches the client until near-expiry, and re-guards
+ *     the no-secrets contract at the transport boundary
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { mockClient } from "aws-sdk-client-mock";
+import { IoTDataPlaneClient, PublishCommand, } from "@aws-sdk/client-iot-data-plane";
+import { createIotPublishPort, defaultRealtimeCredentialsFetcher, } from "./session-heartbeat-publisher";
+const PERSON = "prs_alice";
+const TOPIC = `hq/${PERSON}/sessions`;
+const NOW = new Date("2026-06-15T18:55:00.000Z");
+function credsResponse(expiresInMs) {
+    return {
+        credentials: {
+            accessKeyId: "ASIAEXAMPLE",
+            secretAccessKey: "secret",
+            sessionToken: "token",
+            expiration: new Date(NOW.getTime() + expiresInMs).toISOString(),
+        },
+        iotEndpoint: "abc123-ats.iot.us-east-1.amazonaws.com",
+        region: "us-east-1",
+        topic: TOPIC,
+        expiresAt: new Date(NOW.getTime() + expiresInMs).toISOString(),
+    };
+}
+function cleanPayload() {
+    return {
+        type: "sessions",
+        origin: "outpost",
+        emittedAt: NOW.toISOString(),
+        sessions: [
+            {
+                id: "x",
+                tool: "claude",
+                origin: "outpost",
+                cwd: "/home/ec2-user/hq",
+                project: "hq",
+                company: null,
+                model: "claude-opus-4",
+                status: "running",
+                startedAt: null,
+                lastActivityAt: NOW.toISOString(),
+                source: "/home/ec2-user/.claude/projects/p/x.jsonl",
+            },
+        ],
+    };
+}
+describe("defaultRealtimeCredentialsFetcher", () => {
+    it("POSTs the JWT to /v1/realtime/credentials and returns the parsed body", async () => {
+        const body = credsResponse(3_600_000);
+        const fetchImpl = vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            statusText: "OK",
+            json: async () => body,
+        });
+        const fetcher = defaultRealtimeCredentialsFetcher({
+            apiBaseUrl: "https://hqapi.hq.computer",
+            getJwt: async () => "JWT123",
+            fetchImpl: fetchImpl,
+        });
+        const out = await fetcher();
+        expect(out).toEqual(body);
+        const [url, init] = fetchImpl.mock.calls[0];
+        expect(url).toBe("https://hqapi.hq.computer/v1/realtime/credentials");
+        expect(init.method).toBe("POST");
+        expect(init.headers.authorization).toBe("Bearer JWT123");
+    });
+    it("throws on a non-ok response", async () => {
+        const fetchImpl = vi.fn().mockResolvedValue({
+            ok: false,
+            status: 403,
+            statusText: "Forbidden",
+            json: async () => ({}),
+        });
+        const fetcher = defaultRealtimeCredentialsFetcher({
+            apiBaseUrl: "https://hqapi.hq.computer",
+            getJwt: async () => "JWT",
+            fetchImpl: fetchImpl,
+        });
+        await expect(fetcher()).rejects.toThrow(/403/);
+    });
+});
+describe("createIotPublishPort", () => {
+    const iotMock = mockClient(IoTDataPlaneClient);
+    beforeEach(() => iotMock.reset());
+    it("publishes the payload to the caller's topic via IoT", async () => {
+        iotMock.on(PublishCommand).resolves({});
+        const fetchCredentials = vi.fn().mockResolvedValue(credsResponse(3_600_000));
+        const publish = createIotPublishPort({
+            fetchCredentials,
+            makeClient: () => iotMock,
+            now: () => NOW,
+        });
+        const payload = cleanPayload();
+        await publish(TOPIC, payload);
+        const call = iotMock.commandCalls(PublishCommand)[0];
+        expect(call.args[0].input.topic).toBe(TOPIC);
+        const sent = JSON.parse(Buffer.from(call.args[0].input.payload).toString("utf8"));
+        expect(sent.type).toBe("sessions");
+        expect(sent.sessions[0].id).toBe("x");
+    });
+    it("caches the vended creds/client until near expiry, then re-vends", async () => {
+        iotMock.on(PublishCommand).resolves({});
+        const fetchCredentials = vi
+            .fn()
+            .mockResolvedValueOnce(credsResponse(3_600_000))
+            .mockResolvedValueOnce(credsResponse(3_600_000));
+        const publish = createIotPublishPort({
+            fetchCredentials,
+            makeClient: () => iotMock,
+            now: () => NOW,
+        });
+        await publish(TOPIC, cleanPayload());
+        await publish(TOPIC, cleanPayload());
+        // Second publish reuses the cached client — creds vended once.
+        expect(fetchCredentials).toHaveBeenCalledTimes(1);
+    });
+    it("re-vends when the cached creds are within the refresh skew of expiry", async () => {
+        iotMock.on(PublishCommand).resolves({});
+        const fetchCredentials = vi
+            .fn()
+            // expires in 30s — inside the 60s refresh skew, so every call re-vends
+            .mockResolvedValue(credsResponse(30_000));
+        const publish = createIotPublishPort({
+            fetchCredentials,
+            makeClient: () => iotMock,
+            now: () => NOW,
+        });
+        await publish(TOPIC, cleanPayload());
+        await publish(TOPIC, cleanPayload());
+        expect(fetchCredentials).toHaveBeenCalledTimes(2);
+    });
+    it("re-guards the no-secrets contract at the transport boundary", async () => {
+        iotMock.on(PublishCommand).resolves({});
+        const fetchCredentials = vi.fn().mockResolvedValue(credsResponse(3_600_000));
+        const publish = createIotPublishPort({
+            fetchCredentials,
+            makeClient: () => iotMock,
+            now: () => NOW,
+        });
+        const dirty = cleanPayload();
+        // Smuggle a secret into a whitelisted field — the publisher must refuse.
+        dirty.sessions[0].model = "sk-ant-leaked-key";
+        await expect(publish(TOPIC, dirty)).rejects.toThrow(/secret marker/);
+        expect(iotMock.commandCalls(PublishCommand)).toHaveLength(0);
+    });
+});
+//# sourceMappingURL=session-heartbeat-publisher.test.js.map

package/dist/outposts/session-heartbeat-publisher.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-heartbeat-publisher.test.js","sourceRoot":"","sources":["../../src/outposts/session-heartbeat-publisher.test.ts"],"names":[],"mappings":"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"}

package/dist/outposts/session-heartbeat-retain-guard.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * company-work-corpus US-006 AC7 — no retained MQTT publishes for transcript
+ * objects.
+ *
+ * Session transcripts are pulled on demand via the presign GET path (structural
+ * owner+creator gate); they are NEVER pushed as message bodies over the realtime
+ * fabric. The on-box sessions publisher emits only a COMPACT liveness heartbeat
+ * (`SessionsHeartbeatPayload` — path-only session summaries, guarded by
+ * `assertNoSecretsInPayload`), and it must publish NON-RETAINED so a stale
+ * summary is never re-delivered from the broker to a late subscriber.
+ *
+ * This is a GUARD suite: it asserts the current (correct) behavior so a future
+ * change that (a) turns on `retain` for the sessions topic, or (b) starts
+ * shipping transcript/vault-file bytes over MQTT, fails loudly. No product code
+ * change is expected from US-006 here.
+ */
+export {};
+//# sourceMappingURL=session-heartbeat-retain-guard.test.d.ts.map

package/dist/outposts/session-heartbeat-retain-guard.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-heartbeat-retain-guard.test.d.ts","sourceRoot":"","sources":["../../src/outposts/session-heartbeat-retain-guard.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/outposts/session-heartbeat-retain-guard.test.js

@@ -0,0 +1,106 @@
+/**
+ * company-work-corpus US-006 AC7 — no retained MQTT publishes for transcript
+ * objects.
+ *
+ * Session transcripts are pulled on demand via the presign GET path (structural
+ * owner+creator gate); they are NEVER pushed as message bodies over the realtime
+ * fabric. The on-box sessions publisher emits only a COMPACT liveness heartbeat
+ * (`SessionsHeartbeatPayload` — path-only session summaries, guarded by
+ * `assertNoSecretsInPayload`), and it must publish NON-RETAINED so a stale
+ * summary is never re-delivered from the broker to a late subscriber.
+ *
+ * This is a GUARD suite: it asserts the current (correct) behavior so a future
+ * change that (a) turns on `retain` for the sessions topic, or (b) starts
+ * shipping transcript/vault-file bytes over MQTT, fails loudly. No product code
+ * change is expected from US-006 here.
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { readFileSync } from "node:fs";
+import { mockClient } from "aws-sdk-client-mock";
+import { IoTDataPlaneClient, PublishCommand, } from "@aws-sdk/client-iot-data-plane";
+import { createIotPublishPort, } from "./session-heartbeat-publisher";
+const PERSON = "prs_alice";
+const TOPIC = `hq/${PERSON}/sessions`;
+const NOW = new Date("2026-07-11T18:55:00.000Z");
+function credsResponse() {
+    return {
+        credentials: {
+            accessKeyId: "ASIAEXAMPLE",
+            secretAccessKey: "secret",
+            sessionToken: "token",
+            expiration: new Date(NOW.getTime() + 3_600_000).toISOString(),
+        },
+        iotEndpoint: "abc123-ats.iot.us-east-1.amazonaws.com",
+        region: "us-east-1",
+        topic: TOPIC,
+        expiresAt: new Date(NOW.getTime() + 3_600_000).toISOString(),
+    };
+}
+function cleanPayload() {
+    return {
+        type: "sessions",
+        origin: "outpost",
+        emittedAt: NOW.toISOString(),
+        sessions: [
+            {
+                id: "x",
+                tool: "claude",
+                origin: "outpost",
+                cwd: "/home/ec2-user/hq",
+                project: "hq",
+                company: null,
+                model: "claude-opus-4",
+                status: "running",
+                startedAt: null,
+                lastActivityAt: NOW.toISOString(),
+                source: "/home/ec2-user/.claude/projects/p/x.jsonl",
+            },
+        ],
+    };
+}
+describe("US-006 AC7 — sessions heartbeat is published NON-RETAINED", () => {
+    const iotMock = mockClient(IoTDataPlaneClient);
+    beforeEach(() => iotMock.reset());
+    it("the PublishCommand never sets retain=true", async () => {
+        iotMock.on(PublishCommand).resolves({});
+        const publish = createIotPublishPort({
+            fetchCredentials: vi.fn().mockResolvedValue(credsResponse()),
+            makeClient: () => iotMock,
+            now: () => NOW,
+        });
+        await publish(TOPIC, cleanPayload());
+        const call = iotMock.commandCalls(PublishCommand)[0];
+        // retain must be absent or explicitly false — never true (no broker
+        // re-delivery of a stale session summary; transcripts are pull-only).
+        expect(call.args[0].input.retain).not.toBe(true);
+        // The wire body is the compact summary envelope — no transcript body field.
+        const sent = JSON.parse(Buffer.from(call.args[0].input.payload).toString("utf8"));
+        expect(sent.type).toBe("sessions");
+        // The session summary carries a `source` PATH only, never file/transcript
+        // content — assert no body/content/transcript key ever rides the wire.
+        for (const s of sent.sessions) {
+            expect(s).not.toHaveProperty("body");
+            expect(s).not.toHaveProperty("content");
+            expect(s).not.toHaveProperty("transcript");
+        }
+    });
+});
+describe("US-006 AC7 — static guard: sessions/realtime publishers never retain", () => {
+    // The sessions publisher is the ONLY realtime path in this package that
+    // touches session data, and it may never set retain=true — a retained
+    // message would leave the last session summary sitting on the broker after
+    // the box goes away. (The server-side DM-wake publisher is guarded by the
+    // matching test in hq-pro, which is where that file lives.)
+    const guardedSources = [
+        new URL("./session-heartbeat-publisher.ts", import.meta.url),
+        new URL("./session-heartbeat.ts", import.meta.url),
+    ];
+    it("no guarded publisher sets retain: true", () => {
+        for (const url of guardedSources) {
+            const src = readFileSync(url, "utf8");
+            // Tolerate any whitespace between `retain` and `true`.
+            expect(src).not.toMatch(/retain\s*:\s*true/);
+        }
+    });
+});
+//# sourceMappingURL=session-heartbeat-retain-guard.test.js.map

package/dist/outposts/session-heartbeat-retain-guard.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-heartbeat-retain-guard.test.js","sourceRoot":"","sources":["../../src/outposts/session-heartbeat-retain-guard.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EACL,kBAAkB,EAClB,cAAc,GACf,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,oBAAoB,GAErB,MAAM,+BAA+B,CAAC;AAGvC,MAAM,MAAM,GAAG,WAAW,CAAC;AAC3B,MAAM,KAAK,GAAG,MAAM,MAAM,WAAW,CAAC;AACtC,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,0BAA0B,CAAC,CAAC;AAEjD,SAAS,aAAa;IACpB,OAAO;QACL,WAAW,EAAE;YACX,WAAW,EAAE,aAAa;YAC1B,eAAe,EAAE,QAAQ;YACzB,YAAY,EAAE,OAAO;YACrB,UAAU,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC,WAAW,EAAE;SAC9D;QACD,WAAW,EAAE,wCAAwC;QACrD,MAAM,EAAE,WAAW;QACnB,KAAK,EAAE,KAAK;QACZ,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC,WAAW,EAAE;KAC7D,CAAC;AACJ,CAAC;AAED,SAAS,YAAY;IACnB,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,SAAS;QACjB,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE;QAC5B,QAAQ,EAAE;YACR;gBACE,EAAE,EAAE,GAAG;gBACP,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,SAAS;gBACjB,GAAG,EAAE,mBAAmB;gBACxB,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,IAAI;gBACb,KAAK,EAAE,eAAe;gBACtB,MAAM,EAAE,SAAS;gBACjB,SAAS,EAAE,IAAI;gBACf,cAAc,EAAE,GAAG,CAAC,WAAW,EAAE;gBACjC,MAAM,EAAE,2CAA2C;aACpD;SACF;KACF,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,2DAA2D,EAAE,GAAG,EAAE;IACzE,MAAM,OAAO,GAAG,UAAU,CAAC,kBAAkB,CAAC,CAAC;IAC/C,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAElC,EAAE,CAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;QACzD,OAAO,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,oBAAoB,CAAC;YACnC,gBAAgB,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,aAAa,EAAE,CAAC;YAC5D,UAAU,EAAE,GAAG,EAAE,CAAC,OAAwC;YAC1D,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG;SACf,CAAC,CAAC;QAEH,MAAM,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;QAErC,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;QACrD,oEAAoE;QACpE,sEAAsE;QACtE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,4EAA4E;QAC5E,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CACrB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAqB,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAGvE,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACnC,0EAA0E;QAC1E,uEAAuE;QACvE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC9B,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YACrC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;YACxC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,sEAAsE,EAAE,GAAG,EAAE;IACpF,wEAAwE;IACxE,sEAAsE;IACtE,2EAA2E;IAC3E,0EAA0E;IAC1E,4DAA4D;IAC5D,MAAM,cAAc,GAAG;QACrB,IAAI,GAAG,CAAC,kCAAkC,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;QAC5D,IAAI,GAAG,CAAC,wBAAwB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;KACnD,CAAC;IAEF,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,KAAK,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACtC,uDAAuD;YACvD,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/outposts/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