@indigoai-us/hq-cli 5.345.177 → 5.345.179

package/dist/lib/hot-channels/adapters/attio.js

@@ -0,0 +1,374 @@
+/**
+ * Attio hot channel (hot-signal-sync US-010).
+ *
+ * The Attio webhook receiver in hq-pro-agents
+ * (`src/sources/inbound/attio-events.ts`) is the push half: it lands one
+ * document per delivery in the company vault under `sources/attio/`, with
+ * `event_key: attio:{Idempotency-Key}` in the frontmatter and the webhook
+ * payload in the `.raw.json` sidecar. This adapter is the drain half, a poll
+ * adapter over that folder, the same shape as Slack (US-006). The cursor is
+ * the newest `ingested_at` it has read.
+ *
+ * The hq-pro catalog entry for attio still says `transport: push`. run.ts
+ * plans by the registered adapter's transport, so this adapter runs once per
+ * usable Attio connection either way; changing the catalog entry to `poll` is
+ * an hq-pro follow-up.
+ *
+ * Attio webhooks are workspace-level, so the folder holds every event in the
+ * workspace. Per-person scoping happens here (US-009 rule): a delivery is kept
+ * only when the person's Attio workspace-member id matches
+ *   1. the actor of an event in the delivery,
+ *   2. the owner attribute of the referenced record, or
+ *   3. an assignee or mention on the referenced comment or note.
+ * The member id comes from the person's user-level Attio connection: the
+ * gateway's `list-workspace-members` result, matched by email against the
+ * person's identities. Record owners come from the payload when present and
+ * from the gateway's `get-records-by-ids` otherwise. Assignees and mentions
+ * are read from the payload. With no member id the adapter emits nothing and
+ * leaves the cursor where it was.
+ *
+ * Each landed document is a pointer. Its body is a short header and
+ * `payload_ref` names the landed source document. No payload is copied: the
+ * `.raw.json` sidecar holds the source frontmatter and why the delivery
+ * matched.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { MAX_CATCH_UP_WINDOW_MS } from "../contract.js";
+import { HOT_SIGNAL_ORIGIN } from "../landing.js";
+export const ATTIO_ADAPTER_ID = "attio";
+export const ATTIO_CHANNEL = "attio-events";
+export const ATTIO_PROVIDER = "attio";
+export const ATTIO_SOURCE_DIR = "sources/attio";
+export const ATTIO_RECORD_EVENT = "attio.record";
+export const ATTIO_COMMENT_EVENT = "attio.comment";
+export const ATTIO_NOTE_EVENT = "attio.note";
+export const ATTIO_LIST_MEMBERS_TOOL = "list-workspace-members";
+export const ATTIO_GET_RECORDS_TOOL = "get-records-by-ids";
+/**
+ * Suggestion rule data: Attio is suggested when the person owns a record with
+ * activity in the last 14 days. The contract's `owned-by-me` rule has no
+ * window field, so the window is declared here for the evaluator (US-014).
+ */
+export const ATTIO_SUGGESTION_ACTIVITY_WINDOW_MS = 14 * 24 * 60 * 60 * 1000;
+const DEFAULT_PAGE_SIZE = 100;
+/** Source frontmatter copied to the raw sidecar. */
+const RAW_FIELDS = ["source_id", "event_key", "event_type", "event_count", "ingested_at", "company_id"];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+function parseTime(value) {
+    const stamp = nonEmptyString(value);
+    return stamp === undefined ? NaN : Date.parse(stamp);
+}
+/** Split `---\n{yaml}\n---\n{body}` and return the frontmatter. Unparseable or non-object is null. */
+function readFrontmatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+    if (!match)
+        return null;
+    let parsed;
+    try {
+        parsed = yaml.load(match[1], { schema: yaml.CORE_SCHEMA });
+    }
+    catch {
+        return null;
+    }
+    return isRecord(parsed) ? parsed : null;
+}
+function toDelivery(file, fm) {
+    if (fm.origin === HOT_SIGNAL_ORIGIN)
+        return null;
+    const eventKey = nonEmptyString(fm.event_key);
+    const eventType = nonEmptyString(fm.event_type);
+    const tsMs = parseTime(fm.ingested_at);
+    if (!eventKey?.startsWith("attio:") || !eventType || Number.isNaN(tsMs))
+        return null;
+    const idempotencyKey = eventKey.slice("attio:".length);
+    if (idempotencyKey === "")
+        return null;
+    return {
+        file,
+        sourceId: nonEmptyString(fm.source_id) ?? file.replace(/\.md$/, ""),
+        tsMs,
+        idempotencyKey,
+        eventType,
+        frontmatter: fm,
+    };
+}
+/** The webhook payload's events: `{ events: [...] }`, or the payload itself. */
+function payloadEvents(payload) {
+    if (!isRecord(payload))
+        return [];
+    const events = Array.isArray(payload.events) ? payload.events : [payload];
+    return events.filter(isRecord);
+}
+/** A workspace-member id from an actor-reference shape, or a bare id string. */
+function actorRefId(value) {
+    if (typeof value === "string")
+        return nonEmptyString(value);
+    if (!isRecord(value))
+        return undefined;
+    if (value.type !== undefined && value.type !== "workspace-member")
+        return undefined;
+    if (value.referenced_actor_type !== undefined && value.referenced_actor_type !== "workspace-member")
+        return undefined;
+    return (nonEmptyString(value.referenced_actor_id) ??
+        nonEmptyString(value.workspace_member_id) ??
+        (isRecord(value.id) ? nonEmptyString(value.id.workspace_member_id) : nonEmptyString(value.id)));
+}
+function actorRefIds(value) {
+    const list = Array.isArray(value) ? value : value === undefined ? [] : [value];
+    return list.map(actorRefId).filter((id) => id !== undefined);
+}
+/** Owner ids on a record: `values.owner` (Attio record shape) or a top-level `owner`. */
+function recordOwnerIds(record) {
+    const values = isRecord(record.values) ? record.values : {};
+    return [...actorRefIds(values.owner), ...actorRefIds(record.owner)];
+}
+/** Assignee and mention ids on one event's comment or note, wherever the payload carries them. */
+function assigneeAndMentionIds(evt) {
+    const holders = [evt, evt.comment, evt.note, evt.data].filter(isRecord);
+    const assignees = [];
+    const mentions = [];
+    for (const h of holders) {
+        assignees.push(...actorRefIds(h.assignees), ...actorRefIds(h.assignee));
+        mentions.push(...actorRefIds(h.mentions), ...actorRefIds(h.mentioned_workspace_members));
+    }
+    return { assignees, mentions };
+}
+/** The record an event refers to: `id.{object_id,record_id}`, or a comment/note parent. */
+function recordRef(evt) {
+    const id = isRecord(evt.id) ? evt.id : {};
+    const objectId = nonEmptyString(id.object_id) ?? nonEmptyString(evt.object_id) ?? nonEmptyString(evt.parent_object_id);
+    const recordId = nonEmptyString(id.record_id) ?? nonEmptyString(evt.record_id) ?? nonEmptyString(evt.parent_record_id);
+    return objectId && recordId ? { objectId, recordId } : null;
+}
+/** Unwrap a gateway result: a JSON string, an MCP `content[].text` block, or an object. */
+function unwrapResult(result) {
+    if (typeof result === "string") {
+        try {
+            return JSON.parse(result);
+        }
+        catch {
+            return result;
+        }
+    }
+    if (isRecord(result) && Array.isArray(result.content)) {
+        const text = result.content
+            .map((block) => (isRecord(block) ? nonEmptyString(block.text) : undefined))
+            .find((value) => value !== undefined);
+        if (text !== undefined)
+            return unwrapResult(text);
+    }
+    return result;
+}
+function listOf(body) {
+    if (Array.isArray(body))
+        return body;
+    if (!isRecord(body))
+        return [];
+    for (const key of ["data", "members", "workspace_members", "records"]) {
+        if (Array.isArray(body[key]))
+            return body[key];
+    }
+    return [];
+}
+async function lookupMemberIds(gateway, emails) {
+    if (emails.size === 0)
+        return [];
+    const members = listOf(unwrapResult(await gateway.call(ATTIO_LIST_MEMBERS_TOOL, {})));
+    const ids = [];
+    for (const m of members) {
+        if (!isRecord(m))
+            continue;
+        const email = nonEmptyString(m.email_address) ?? nonEmptyString(m.email);
+        const id = actorRefId(m);
+        if (email && id && emails.has(email.toLowerCase()))
+            ids.push(id);
+    }
+    return ids;
+}
+async function lookupOwnerIds(gateway, ref) {
+    const records = listOf(unwrapResult(await gateway.call(ATTIO_GET_RECORDS_TOOL, { object: ref.objectId, record_ids: [ref.recordId] })));
+    return records.filter(isRecord).flatMap(recordOwnerIds);
+}
+function eventWhat(eventType) {
+    if (eventType.startsWith("comment."))
+        return ATTIO_COMMENT_EVENT;
+    if (eventType.startsWith("note"))
+        return ATTIO_NOTE_EVENT;
+    return ATTIO_RECORD_EVENT;
+}
+function byTimeThenName(a, b) {
+    return a.tsMs - b.tsMs || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
+}
+export function createAttioAdapter(options) {
+    const dir = path.join(options.vaultRoot, ATTIO_SOURCE_DIR);
+    const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+    if (!Number.isInteger(pageSize) || pageSize < 1)
+        throw new Error("attio pageSize must be a positive integer");
+    async function readPayload(d) {
+        try {
+            return JSON.parse(await fs.readFile(path.join(dir, `${d.file.replace(/\.md$/, "")}.raw.json`), "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    async function fetch(cursor, ctx) {
+        let names;
+        try {
+            names = await fs.readdir(dir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return { events: [], cursor, hasMore: false };
+            throw err;
+        }
+        const identities = [ctx.personUid, ...(options.identities ?? [])].filter((id) => id !== "");
+        const emails = new Set(identities.filter((id) => id.includes("@")).map((id) => id.toLowerCase()));
+        const memberIds = new Set((options.memberIds && options.memberIds.length > 0
+            ? [...options.memberIds]
+            : ctx.gateway
+                ? await lookupMemberIds(ctx.gateway, emails)
+                : []).map((id) => id.toLowerCase()));
+        // Without the person's member id nothing can be scoped to them: emit
+        // nothing and keep the cursor, so the deliveries are read once it resolves.
+        if (memberIds.size === 0)
+            return { events: [], cursor, hasMore: false };
+        const isMe = (id) => memberIds.has(id.toLowerCase());
+        const sinceMs = Date.parse(ctx.since);
+        const cursorMs = cursor === null ? NaN : Date.parse(cursor);
+        const candidates = [];
+        for (const file of names.filter((n) => n.endsWith(".md")).sort()) {
+            let text;
+            try {
+                text = await fs.readFile(path.join(dir, file), "utf8");
+            }
+            catch {
+                continue;
+            }
+            const fm = readFrontmatter(text);
+            const d = fm ? toDelivery(file, fm) : null;
+            if (!d || d.tsMs < sinceMs)
+                continue;
+            if (!Number.isNaN(cursorMs) && d.tsMs < cursorMs)
+                continue;
+            candidates.push(d);
+        }
+        candidates.sort(byTimeThenName);
+        // Deliveries at the cursor time are re-read every page so one landing later
+        // with the same ingest time is not lost; landing drops the duplicates. A
+        // page never splits one timestamp. The cursor moves past every delivery on
+        // the page, kept or not.
+        const atCursor = candidates.filter((d) => d.tsMs === cursorMs);
+        const newer = Number.isNaN(cursorMs) ? candidates : candidates.filter((d) => d.tsMs > cursorMs);
+        let end = Math.min(pageSize, newer.length);
+        while (end > 0 && end < newer.length && newer[end].tsMs === newer[end - 1].tsMs)
+            end += 1;
+        const page = newer.slice(0, end);
+        const ownerCache = new Map();
+        const ownersOf = (ref) => {
+            const key = `${ref.objectId}/${ref.recordId}`;
+            let hit = ownerCache.get(key);
+            if (!hit) {
+                hit = ctx.gateway ? lookupOwnerIds(ctx.gateway, ref) : Promise.resolve([]);
+                ownerCache.set(key, hit);
+            }
+            return hit;
+        };
+        const events = [];
+        for (const d of [...atCursor, ...page]) {
+            const evts = payloadEvents(await readPayload(d));
+            const reasons = new Set();
+            let actor;
+            let ref = null;
+            for (const evt of evts) {
+                const actorId = actorRefId(evt.actor);
+                actor ??= actorId;
+                if (actorId && isMe(actorId))
+                    reasons.add("actor");
+                const { assignees, mentions } = assigneeAndMentionIds(evt);
+                if (assignees.some(isMe))
+                    reasons.add("assignee");
+                if (mentions.some(isMe))
+                    reasons.add("mention");
+                ref ??= recordRef(evt);
+                const inline = [evt.record, evt.data].filter(isRecord).flatMap(recordOwnerIds);
+                if (inline.some(isMe))
+                    reasons.add("owner");
+            }
+            if (reasons.size === 0 && ref && (await ownersOf(ref)).some(isMe))
+                reasons.add("owner");
+            if (reasons.size === 0)
+                continue;
+            events.push(toEvent(d, [...reasons], actor, ref, ctx.personUid, options.identities));
+        }
+        const last = page[page.length - 1];
+        return {
+            events,
+            cursor: last ? new Date(last.tsMs).toISOString() : cursor,
+            hasMore: end < newer.length,
+        };
+    }
+    return {
+        id: ATTIO_ADAPTER_ID,
+        channel: ATTIO_CHANNEL,
+        transport: "poll",
+        hotEventTypes: [ATTIO_RECORD_EVENT, ATTIO_COMMENT_EVENT, ATTIO_NOTE_EVENT],
+        catchUpWindow: { maxLookbackMs: MAX_CATCH_UP_WINDOW_MS },
+        tokenScope: { provider: ATTIO_PROVIDER, scopes: [] },
+        // Records the person owns with activity in the last
+        // ATTIO_SUGGESTION_ACTIVITY_WINDOW_MS (14 days).
+        suggestionRule: { kind: "owned-by-me" },
+        fetch,
+    };
+}
+function toEvent(d, reasons, actor, ref, personUid, identities) {
+    const fm = d.frontmatter;
+    const when = new Date(d.tsMs).toISOString();
+    const what = eventWhat(d.eventType);
+    const where = ref ? `attio:${ref.objectId}/${ref.recordId}` : "attio";
+    const person = identities?.find((id) => id.startsWith("prs_")) ?? personUid;
+    const payloadRef = `${ATTIO_SOURCE_DIR}/${d.file}`;
+    const title = `Attio ${d.eventType}`;
+    const body = [
+        `# ${title}`,
+        "",
+        `- When: ${when}`,
+        `- Who: ${actor ?? "unknown"}`,
+        `- Matched: ${reasons.join(", ")}`,
+        `- Where: ${where}`,
+        `- Source: ${payloadRef}`,
+        "",
+    ].join("\n");
+    const raw = {};
+    for (const field of RAW_FIELDS)
+        if (fm[field] !== undefined)
+            raw[field] = fm[field];
+    return {
+        providerId: d.idempotencyKey,
+        // The receiver dedupes by Idempotency-Key, so one delivery has one version.
+        version: d.eventType,
+        who: actor ?? "unknown",
+        what,
+        where,
+        when,
+        audience: [person],
+        title,
+        body,
+        payloadRef,
+        frontmatter: {
+            audience_source: "person_uid",
+            attio_event_type: d.eventType,
+            attio_match: reasons.join(","),
+            ...(ref ? { attio_object_id: ref.objectId, attio_record_id: ref.recordId } : {}),
+        },
+        raw: { source: payloadRef, ...raw, matched: reasons, actor: actor ?? null, record: ref },
+    };
+}
+//# sourceMappingURL=attio.js.map

package/dist/lib/hot-channels/adapters/gmail.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Gmail hot channel (hot-signal-sync US-013), flag-gated.
+ *
+ * A poll adapter over the person's Google connection, routed through the HQ
+ * gateway. It watches INBOX with `users.watch`, renewed daily, and reads new
+ * mail with `history.list` from the stored `historyId`. The token stays in the
+ * gateway; this adapter never sees it.
+ *
+ * The adapter is always registered. It declares `gate.flag`, and the catalog
+ * lists gmail only when that flag is on for the company. With the flag off,
+ * `hq sources sync` reports gmail as `gated` and never calls this adapter.
+ *
+ * Gateway tools: the HQ google provider does not expose these four tools yet.
+ * They are named here as constants, and a follow-up hq-pro story adds them
+ * (all within `gmail.readonly`) before the flag turns on. The argument shapes
+ * are recorded in the project design note US-013-gmail-gateway-tools.md.
+ *
+ * The cursor is a JSON object `{ historyId, watchExpiresAt, watchedAt, pageToken }`:
+ * - `historyId`: Gmail history at or before it was already read.
+ * - `watchExpiresAt` / `watchedAt`: when the INBOX watch expires and when it
+ *   was last renewed. The watch is renewed when it was never set up, when it
+ *   is 24 hours old or older, or when it expires in under 24 hours.
+ * - `pageToken`: the `history.list` page token while a pass is in progress.
+ *   The pass keeps the old `historyId` until its last page, then advances to
+ *   the response's top-level `historyId`.
+ *
+ * A first run seeds `historyId` from the watch response (or `users.getProfile`)
+ * and lands nothing: Gmail history only exists after a known `historyId`.
+ * When Google answers 404 because the stored `historyId` is too old (about a
+ * week), the adapter re-seeds the same way and lands nothing.
+ *
+ * Each landed document is a pointer: subject, from, to, date and thread id
+ * from a metadata-only `messages.get`. The adapter never requests or copies a
+ * message body or snippet. The event key is `gmail:{messageId}:{historyId}`,
+ * with the history record id as the version.
+ *
+ * A revoked or expired token surfaces from the gateway call; run.ts turns it
+ * into a reconnect prompt in the run ledger and the cursor does not move.
+ */
+import { type PollHotChannelAdapter } from "../contract.js";
+export declare const GMAIL_ADAPTER_ID = "gmail";
+export declare const GMAIL_CHANNEL = "gmail";
+export declare const GMAIL_PROVIDER = "google";
+export declare const GMAIL_READONLY_SCOPE = "https://www.googleapis.com/auth/gmail.readonly";
+/** The flag registered in hq-pro `src/flags/keys.ts`. */
+export declare const GMAIL_FLAG = "hq.hot-channel-gmail";
+export declare const GMAIL_MESSAGE_ADDED_EVENT = "gmail.message.added";
+export declare const GMAIL_LABEL_ADDED_EVENT = "gmail.label.added";
+export declare const GMAIL_WATCH_TOOL = "google.gmail.users.watch";
+export declare const GMAIL_HISTORY_LIST_TOOL = "google.gmail.history.list";
+export declare const GMAIL_GET_PROFILE_TOOL = "google.gmail.users.getProfile";
+export declare const GMAIL_GET_MESSAGE_TOOL = "google.gmail.messages.get";
+export declare const GMAIL_INBOX_LABEL = "INBOX";
+export declare const GMAIL_METADATA_HEADERS: readonly ["Subject", "From", "To", "Date"];
+export declare const GMAIL_CATCH_UP_WINDOW_MS: number;
+/** Renew the watch at least this often, and when it expires sooner than this. */
+export declare const GMAIL_WATCH_RENEW_MS: number;
+export interface GmailAdapterOptions {
+    /** History records per `history.list` call. Clamped to 1..500. Default 100. */
+    pageSize?: number;
+    /** Clock for watch renewal and event times without a Date header. */
+    now?: () => Date;
+}
+/** The adapter's cursor: see the file comment. */
+export interface GmailCursor {
+    historyId: string;
+    watchExpiresAt: string | null;
+    watchedAt: string | null;
+    pageToken: string | null;
+}
+/** The headers a landed pointer carries. Never a body or snippet. */
+export interface GmailMessageHeaders {
+    subject?: string;
+    from?: string;
+    to?: string;
+    date?: string;
+}
+/** The `.raw.json` sidecar of a landed Gmail event. */
+export interface GmailPointer {
+    messageId: string;
+    threadId?: string;
+    historyId: string;
+    labelIds: string[];
+    headers: GmailMessageHeaders;
+}
+interface HistoryChange {
+    kind: typeof GMAIL_MESSAGE_ADDED_EVENT | typeof GMAIL_LABEL_ADDED_EVENT;
+    historyId: string;
+    messageId: string;
+    threadId?: string;
+    labelIds: string[];
+}
+interface HistoryPage {
+    changes: HistoryChange[];
+    nextPageToken: string | null;
+    historyId: string | null;
+}
+export declare function parseGmailCursor(cursor: string | null): GmailCursor | null;
+/** True when the INBOX watch must be set up or renewed now. */
+export declare function gmailWatchDue(cursor: GmailCursor | null, now: Date): boolean;
+/** Google's answer when `startHistoryId` is older than the history it keeps. */
+export declare function isExpiredHistoryError(err: unknown): boolean;
+/** Parse one `history.list` page into INBOX message and label changes. */
+export declare function parseGmailHistoryPage(result: unknown): HistoryPage;
+/** Headers from a metadata-format `messages.get`. Body, snippet and parts are ignored. */
+export declare function parseGmailMessageHeaders(result: unknown): GmailMessageHeaders & {
+    internalDate?: string;
+};
+export declare function createGmailAdapter(options?: GmailAdapterOptions): PollHotChannelAdapter;
+export {};
+//# sourceMappingURL=gmail.d.ts.map