@indigoai-us/hq-cli 5.345.190 → 5.345.193

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

@@ -4,8 +4,10 @@
  * 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
+ * `event_key: attio:{deliveryHash}` in the frontmatter, where deliveryHash is
+ * `sha256hex(Idempotency-Key + "\n" + rawBody)` (the raw key is kept in a
+ * separate `idempotency_key` field), 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.
  *
@@ -31,12 +33,56 @@
  * `payload_ref` names the landed source document. No payload is copied: the
  * `.raw.json` sidecar holds the source frontmatter and why the delivery
  * matched.
+ *
+ * US-010 adds a gateway pull as the catch-up path alongside the drain, for
+ * changes whose webhook never landed. Once the drain has no more pages, each
+ * fetch asks the gateway for records (`list-records`, one call per object in
+ * `pullObjects`, filtered `created_at > watermark`, sorted ascending, limit
+ * 50) and notes (`search-notes-by-metadata` with `created_at_gt`) newer than
+ * that source's watermark. A pulled item is kept on the same rule as a
+ * delivery: the person created it or owns its record. The Attio gateway has
+ * no updated-at filter on records, so record updates still come from the
+ * webhook drain; the pull catches records and notes that were created.
+ *
+ * Event keys follow the US-008 shape `attio:{recordId}:{eventId}`, built from
+ * Attio ids both paths have, so a create the webhook delivered and the pull
+ * found lands once:
+ *   - a create (a delivery holding one `record.created` or `note.created`
+ *     event, or a pulled record or note) is `attio:{record_id}:record.created`
+ *     or `attio:{note_id}:note.created`;
+ *   - every other delivery is `attio:{subjectId}:{deliveryHash}`, where the
+ *     subject is the note, comment, record or entry the first event names, so
+ *     two updates to one record stay two items.
+ *
+ * The cursor is JSON `{ drain, pull }`: `drain` is the newest `ingested_at`
+ * read, and `pull` maps `records:{object}` and `notes` to the newest
+ * `created_at` read. A plain ISO string from before US-010 reads as `drain`.
+ *
+ * Upgrading from the drain before US-010 (re-review C): that drain keyed every
+ * delivery `attio:{deliveryHash}:{event_type}`, and a plain ISO cursor gives
+ * the pull no watermark, so the first pull reads the whole catch-up window.
+ * Landing dedupes on the event key alone (the landed document's path), so
+ * nothing the old drain landed may come back under a new key:
+ *   - the drain keeps the old key for a delivery whose document under the old
+ *     key is already landed (the deliveries at the old cursor are re-read);
+ *   - the pull gives a create the old key of the landed delivery that carried
+ *     it, so landing reports a duplicate.
+ * A create the old drain never landed (its webhook was lost, or it is newer
+ * than the old cursor) has no document under an old key and lands under the
+ * new one. The pull watermark is not seeded from the old cursor, so those
+ * lost creates are not skipped.
+ *
+ * Rate limits: every gateway call retries a 429 with backoff (Retry-After
+ * when Attio sends it), at most ATTIO_MAX_RETRIES times, and one fetch makes
+ * at most ATTIO_MAX_REQUESTS_PER_FETCH calls. A persistent 429 or the cap
+ * throws AttioRateLimitedError before a cursor is returned, so the watermark
+ * stays where it was.
  */
 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";
+import { eventKey, HOT_SIGNAL_ORIGIN, hotSourceId } from "../landing.js";
 export const ATTIO_ADAPTER_ID = "attio";
 export const ATTIO_CHANNEL = "attio-events";
 export const ATTIO_PROVIDER = "attio";
@@ -46,6 +92,17 @@ 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";
+export const ATTIO_LIST_RECORDS_TOOL = "list-records";
+export const ATTIO_SEARCH_NOTES_TOOL = "search-notes-by-metadata";
+/** Records per `list-records` call; the Attio policy caps it at 50. */
+export const ATTIO_PULL_LIMIT = 50;
+/** Objects the catch-up pull lists by default. */
+export const ATTIO_DEFAULT_PULL_OBJECTS = ["companies", "people", "deals"];
+export const ATTIO_MAX_RETRIES = 3;
+const ATTIO_BASE_BACKOFF_MS = 1000;
+const ATTIO_MAX_BACKOFF_MS = 30_000;
+/** Gateway calls one fetch may make, retries included. */
+export const ATTIO_MAX_REQUESTS_PER_FETCH = 200;
 /**
  * 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
@@ -53,6 +110,85 @@ export const ATTIO_GET_RECORDS_TOOL = "get-records-by-ids";
  */
 export const ATTIO_SUGGESTION_ACTIVITY_WINDOW_MS = 14 * 24 * 60 * 60 * 1000;
 const DEFAULT_PAGE_SIZE = 100;
+/** Attio kept answering 429 after every retry, or the run hit its request cap; the cursor stays put. */
+export class AttioRateLimitedError extends Error {
+    retryAfterMs;
+    code = "rate_limited";
+    status = 429;
+    constructor(retryAfterMs) {
+        super("Attio rate limit (429): the run stopped and will resume from the same cursor next time");
+        this.retryAfterMs = retryAfterMs;
+        this.name = "AttioRateLimitedError";
+    }
+}
+/** Parse a stored cursor. A plain ISO string (before US-010) is the drain cursor. */
+export function parseAttioCursor(raw) {
+    if (raw === null || raw === "")
+        return { drain: null, pull: {} };
+    if (raw.trimStart().startsWith("{")) {
+        try {
+            const parsed = JSON.parse(raw);
+            const pull = {};
+            if (isRecord(parsed.pull)) {
+                for (const [k, v] of Object.entries(parsed.pull))
+                    if (typeof v === "string" && !Number.isNaN(Date.parse(v)))
+                        pull[k] = v;
+            }
+            return { drain: typeof parsed.drain === "string" ? parsed.drain : null, pull };
+        }
+        catch {
+            return { drain: null, pull: {} };
+        }
+    }
+    return { drain: raw, pull: {} };
+}
+const RATE_LIMIT_PATTERN = /\b429\b|rate[ _-]?limit|too many requests/i;
+function isRateLimited(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const e = err;
+    if (e.status === 429 || e.statusCode === 429)
+        return true;
+    if (typeof e.code === "string" && RATE_LIMIT_PATTERN.test(e.code))
+        return true;
+    return typeof e.message === "string" && RATE_LIMIT_PATTERN.test(e.message);
+}
+function retryAfterMs(err) {
+    const e = err;
+    let raw = e?.retryAfter;
+    if (raw === undefined && e?.headers && typeof e.headers === "object") {
+        const h = e.headers;
+        raw = typeof h.get === "function" ? h.get("retry-after") : (h["retry-after"] ?? h["Retry-After"]);
+    }
+    const secs = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : NaN;
+    return Number.isFinite(secs) && secs >= 0 ? secs * 1000 : null;
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** A gateway whose calls retry 429s with backoff and stop at the per-fetch request cap. */
+function retryingGateway(gateway, sleep) {
+    let requests = 0;
+    return {
+        ...gateway,
+        async call(tool, args) {
+            for (let attempt = 0;; attempt++) {
+                if (requests >= ATTIO_MAX_REQUESTS_PER_FETCH)
+                    throw new AttioRateLimitedError(null);
+                requests++;
+                try {
+                    return await gateway.call(tool, args);
+                }
+                catch (err) {
+                    if (!isRateLimited(err))
+                        throw err;
+                    const wait = retryAfterMs(err);
+                    if (attempt >= ATTIO_MAX_RETRIES)
+                        throw new AttioRateLimitedError(wait);
+                    await sleep(Math.min(ATTIO_MAX_BACKOFF_MS, wait ?? ATTIO_BASE_BACKOFF_MS * 2 ** attempt));
+                }
+            }
+        },
+    };
+}
 /** 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) {
@@ -87,14 +223,14 @@ function toDelivery(file, fm) {
     const tsMs = parseTime(fm.ingested_at);
     if (!eventKey?.startsWith("attio:") || !eventType || Number.isNaN(tsMs))
         return null;
-    const idempotencyKey = eventKey.slice("attio:".length);
-    if (idempotencyKey === "")
+    const deliveryHash = eventKey.slice("attio:".length);
+    if (deliveryHash === "")
         return null;
     return {
         file,
         sourceId: nonEmptyString(fm.source_id) ?? file.replace(/\.md$/, ""),
         tsMs,
-        idempotencyKey,
+        deliveryHash,
         eventType,
         frontmatter: fm,
     };
@@ -147,6 +283,31 @@ function recordRef(evt) {
     const recordId = nonEmptyString(id.record_id) ?? nonEmptyString(evt.record_id) ?? nonEmptyString(evt.parent_record_id);
     return objectId && recordId ? { objectId, recordId } : null;
 }
+/** Create events the gateway pull can also find; keyed by Attio id and event type on both paths. */
+const ATTIO_CREATE_EVENTS = new Set(["record.created", "note.created"]);
+/** The Attio id an event is about: its note, comment, record or list entry. */
+function subjectId(evt) {
+    const id = isRecord(evt.id) ? evt.id : {};
+    return (nonEmptyString(id.note_id) ??
+        nonEmptyString(id.comment_id) ??
+        nonEmptyString(id.record_id) ??
+        nonEmptyString(id.entry_id));
+}
+/**
+ * `providerId` and `version` for one delivery (event_key
+ * `attio:{providerId}:{version}`). A delivery holding exactly one create keys
+ * on the created record or note and the event type, the same key the pull
+ * gives that create. Anything else keys on its subject and the delivery hash.
+ */
+function deliveryKey(d, evts, ref) {
+    const only = evts.length === 1 ? evts[0] : undefined;
+    const type = only ? (nonEmptyString(only.event_type) ?? d.eventType) : d.eventType;
+    const subject = only ? subjectId(only) : undefined;
+    if (only && subject && ATTIO_CREATE_EVENTS.has(type))
+        return { providerId: subject, version: type };
+    const first = evts.map(subjectId).find((id) => id !== undefined);
+    return { providerId: first ?? ref?.recordId ?? d.deliveryHash, version: d.deliveryHash };
+}
 /** Unwrap a gateway result: a JSON string, an MCP `content[].text` block, or an object. */
 function unwrapResult(result) {
     if (typeof result === "string") {
@@ -219,28 +380,181 @@ export function createAttioAdapter(options) {
             return null;
         }
     }
-    async function fetch(cursor, ctx) {
+    const pullObjects = options.pullObjects ?? ATTIO_DEFAULT_PULL_OBJECTS;
+    const sleep = options.sleep ?? defaultSleep;
+    /** The key the drain before US-010 gave a delivery: `attio:{deliveryHash}:{event_type}`. */
+    const legacyKey = (d) => ({
+        providerId: d.deliveryHash,
+        version: d.eventType,
+    });
+    /** True when the drain before US-010 landed this delivery: its document under the old key exists. */
+    async function landedUnderLegacyKey(d) {
+        const key = legacyKey(d);
+        const sourceId = hotSourceId(ATTIO_ADAPTER_ID, eventKey(ATTIO_ADAPTER_ID, key.providerId, key.version));
+        try {
+            await fs.stat(path.join(options.vaultRoot, "sources", ATTIO_CHANNEL, `${sourceId}.md`));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Creates the drain before US-010 already landed, by `{event type}\n{id}`,
+     * mapped to the old key of the landed delivery that carried them. Only
+     * deliveries inside the catch-up window can match a pulled create.
+     */
+    async function legacyLandedCreates(sinceMs) {
+        const out = new Map();
         let names;
         try {
             names = await fs.readdir(dir);
         }
-        catch (err) {
-            if (err.code === "ENOENT")
-                return { events: [], cursor, hasMore: false };
-            throw err;
+        catch {
+            return out;
         }
+        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 || (!Number.isNaN(sinceMs) && d.tsMs < sinceMs))
+                continue;
+            if (!(await landedUnderLegacyKey(d)))
+                continue;
+            for (const evt of payloadEvents(await readPayload(d))) {
+                const type = nonEmptyString(evt.event_type) ?? d.eventType;
+                const subject = subjectId(evt);
+                if (subject && ATTIO_CREATE_EVENTS.has(type))
+                    out.set(`${type}\n${subject}`, legacyKey(d));
+            }
+        }
+        return out;
+    }
+    async function fetch(rawCursor, ctx) {
+        const gateway = ctx.gateway ? retryingGateway(ctx.gateway, sleep) : undefined;
+        const state = parseAttioCursor(rawCursor);
         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)
+            : gateway
+                ? await lookupMemberIds(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 };
+            return { events: [], cursor: rawCursor, hasMore: false };
         const isMe = (id) => memberIds.has(id.toLowerCase());
+        const ownerCache = new Map();
+        const ownersOf = (ref) => {
+            const key = `${ref.objectId}/${ref.recordId}`;
+            let hit = ownerCache.get(key);
+            if (!hit) {
+                hit = gateway ? lookupOwnerIds(gateway, ref) : Promise.resolve([]);
+                ownerCache.set(key, hit);
+            }
+            return hit;
+        };
+        const drained = await drain(state.drain, ctx, isMe, ownersOf);
+        const next = { drain: drained.cursor, pull: { ...state.pull } };
+        const events = [...drained.events];
+        let hasMore = drained.hasMore;
+        // The catch-up pull runs once the drain is caught up.
+        if (gateway && !hasMore) {
+            const pulled = await pull(gateway, state.pull, ctx, isMe, ownersOf);
+            events.push(...pulled.events);
+            next.pull = pulled.watermarks;
+            hasMore = pulled.hasMore;
+        }
+        return { events, cursor: JSON.stringify(next), hasMore };
+    }
+    async function pull(gateway, watermarks, ctx, isMe, ownersOf) {
+        const out = { ...watermarks };
+        const events = [];
+        let hasMore = false;
+        const sinceMs = Date.parse(ctx.since);
+        // Read once per fetch, and only when the pull has a create to check.
+        let legacy;
+        const keyed = async (event) => {
+            legacy ??= legacyLandedCreates(sinceMs);
+            const old = (await legacy).get(`${event.version}\n${event.providerId}`);
+            return old ? { ...event, ...old } : event;
+        };
+        const floor = (key) => {
+            const mark = out[key];
+            if (mark && (Number.isNaN(sinceMs) || Date.parse(mark) >= sinceMs))
+                return mark;
+            return new Date(Number.isNaN(sinceMs) ? 0 : sinceMs).toISOString();
+        };
+        for (const object of pullObjects) {
+            const key = `records:${object}`;
+            const after = floor(key);
+            const rows = listOf(unwrapResult(await gateway.call(ATTIO_LIST_RECORDS_TOOL, {
+                object,
+                filter: { attribute: "created_at", op: "gt", value: after },
+                sorts: [{ attribute: "created_at", direction: "asc" }],
+                limit: ATTIO_PULL_LIMIT,
+            }))).filter(isRecord);
+            if (rows.length >= ATTIO_PULL_LIMIT)
+                hasMore = true;
+            let newest = after;
+            for (const row of rows) {
+                const created = nonEmptyString(row.created_at);
+                const id = isRecord(row.id) ? nonEmptyString(row.id.record_id) : nonEmptyString(row.id);
+                if (!created || Number.isNaN(Date.parse(created)) || !id)
+                    continue;
+                if (Date.parse(created) > Date.parse(newest))
+                    newest = new Date(Date.parse(created)).toISOString();
+                if (!recordOwnerIds(row).some(isMe))
+                    continue;
+                if (ctx.selection && !ctx.selection.has(id))
+                    continue;
+                events.push(await keyed(pulledEvent("record", object, id, created, ctx.personUid, options.identities)));
+            }
+            out[key] = newest;
+        }
+        const after = floor("notes");
+        const notes = listOf(unwrapResult(await gateway.call(ATTIO_SEARCH_NOTES_TOOL, { created_at_gt: after, limit: ATTIO_PULL_LIMIT }))).filter(isRecord);
+        if (notes.length >= ATTIO_PULL_LIMIT)
+            hasMore = true;
+        let newest = after;
+        for (const note of notes) {
+            const created = nonEmptyString(note.created_at);
+            const id = isRecord(note.id) ? nonEmptyString(note.id.note_id) : nonEmptyString(note.id);
+            if (!created || Number.isNaN(Date.parse(created)) || !id)
+                continue;
+            if (Date.parse(created) > Date.parse(newest))
+                newest = new Date(Date.parse(created)).toISOString();
+            const parentObject = nonEmptyString(note.parent_object);
+            const parentId = nonEmptyString(note.parent_record_id);
+            const ref = parentObject && parentId ? { objectId: parentObject, recordId: parentId } : null;
+            const author = actorRefId(note.created_by_actor);
+            const mine = (author !== undefined && isMe(author)) || (ref !== null && (await ownersOf(ref)).some(isMe));
+            if (!mine)
+                continue;
+            if (ctx.selection && !(ref && ctx.selection.has(ref.recordId)))
+                continue;
+            events.push(await keyed(pulledEvent("note", parentObject ?? "note", id, created, ctx.personUid, options.identities, ref, author)));
+        }
+        out.notes = newest;
+        return { events, watermarks: out, hasMore };
+    }
+    async function drain(cursor, ctx, isMe, ownersOf) {
+        let names;
+        try {
+            names = await fs.readdir(dir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return { events: [], cursor, hasMore: false };
+            throw err;
+        }
         const sinceMs = Date.parse(ctx.since);
         const cursorMs = cursor === null ? NaN : Date.parse(cursor);
         const candidates = [];
@@ -271,16 +585,6 @@ export function createAttioAdapter(options) {
         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));
@@ -309,7 +613,9 @@ export function createAttioAdapter(options) {
             // A saved record pick: only deliveries about a chosen record land.
             if (ctx.selection && !(ref && ctx.selection.has(ref.recordId)))
                 continue;
-            events.push(toEvent(d, [...reasons], actor, ref, ctx.personUid, options.identities));
+            // A delivery the drain before US-010 landed keeps its old key (see the file comment).
+            const key = (await landedUnderLegacyKey(d)) ? legacyKey(d) : deliveryKey(d, evts, ref);
+            events.push(toEvent(d, key, [...reasons], actor, ref, ctx.personUid, options.identities));
         }
         const last = page[page.length - 1];
         return {
@@ -320,6 +626,9 @@ export function createAttioAdapter(options) {
     }
     return {
         id: ATTIO_ADAPTER_ID,
+        displayName: "Attio",
+        provider: ATTIO_PROVIDER,
+        watermarkKind: "timestamp",
         channel: ATTIO_CHANNEL,
         transport: "poll",
         hotEventTypes: [ATTIO_RECORD_EVENT, ATTIO_COMMENT_EVENT, ATTIO_NOTE_EVENT],
@@ -331,7 +640,35 @@ export function createAttioAdapter(options) {
         fetch,
     };
 }
-function toEvent(d, reasons, actor, ref, personUid, identities) {
+/** A pointer event for a record or note the catch-up pull found. Nothing from the record is copied. */
+function pulledEvent(kind, object, id, createdAt, personUid, identities, parent = null, author) {
+    const when = new Date(Date.parse(createdAt)).toISOString();
+    const person = identities?.find((i) => i.startsWith("prs_")) ?? personUid;
+    const ref = kind === "record" ? { objectId: object, recordId: id } : parent;
+    const where = ref ? `attio:${ref.objectId}/${ref.recordId}` : "attio";
+    const title = kind === "record" ? `Attio ${object} record created` : "Attio note created";
+    const body = [`# ${title}`, "", `- When: ${when}`, `- Who: ${author ?? "unknown"}`, `- Where: ${where}`, "- Source: gateway pull", ""].join("\n");
+    return {
+        // Same key as the webhook delivery of this create: attio:{id}:{event type}.
+        providerId: id,
+        version: kind === "record" ? "record.created" : "note.created",
+        who: author ?? "unknown",
+        what: kind === "record" ? ATTIO_RECORD_EVENT : ATTIO_NOTE_EVENT,
+        where,
+        when,
+        audience: [person],
+        title,
+        body,
+        frontmatter: {
+            audience_source: "person_uid",
+            attio_origin: "gateway-pull",
+            ...(ref ? { attio_object_id: ref.objectId, attio_record_id: ref.recordId } : {}),
+            ...(kind === "note" ? { attio_note_id: id } : {}),
+        },
+        raw: { source: "gateway-pull", kind, object, id, created_at: when, record: ref },
+    };
+}
+function toEvent(d, key, reasons, actor, ref, personUid, identities) {
     const fm = d.frontmatter;
     const when = new Date(d.tsMs).toISOString();
     const what = eventWhat(d.eventType);
@@ -354,9 +691,10 @@ function toEvent(d, reasons, actor, ref, personUid, identities) {
         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,
+        // See deliveryKey: a create keys on the Attio id and event type, anything
+        // else on its subject and the receiver's delivery hash.
+        providerId: key.providerId,
+        version: key.version,
         who: actor ?? "unknown",
         what,
         where,

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

@@ -60,7 +60,21 @@ export interface GmailAdapterOptions {
     pageSize?: number;
     /** Clock for watch renewal and event times without a Date header. */
     now?: () => Date;
+    /** Waits between rate-limit retries. Tests pass a fake. */
+    sleep?: (ms: number) => Promise<void>;
 }
+/** Gmail kept answering 429 after every retry; the cursor stays put. */
+export declare class GmailRateLimitedError extends Error {
+    readonly retryAfterMs: number | null;
+    readonly code = "rate_limited";
+    readonly status = 429;
+    constructor(retryAfterMs: number | null);
+}
+/** Every call reads only the connected person's own mailbox. */
+export declare const GMAIL_USER_ID = "me";
+export declare const GMAIL_MAX_RETRIES = 3;
+/** Gateway calls one fetch may make, retries included, before it stops with the cursor unmoved. */
+export declare const GMAIL_MAX_REQUESTS_PER_FETCH = 1000;
 /** The adapter's cursor: see the file comment. */
 export interface GmailCursor {
     historyId: string;

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

@@ -57,6 +57,24 @@ export const GMAIL_WATCH_RENEW_MS = 24 * 60 * 60 * 1000;
 const SUGGESTION_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
 const DEFAULT_PAGE_SIZE = 100;
 const MAX_PAGE_SIZE = 500;
+/** Gmail kept answering 429 after every retry; the cursor stays put. */
+export class GmailRateLimitedError extends Error {
+    retryAfterMs;
+    code = "rate_limited";
+    status = 429;
+    constructor(retryAfterMs) {
+        super("Gmail rate limit (429): the run stopped and will resume from the same cursor next time");
+        this.retryAfterMs = retryAfterMs;
+        this.name = "GmailRateLimitedError";
+    }
+}
+/** Every call reads only the connected person's own mailbox. */
+export const GMAIL_USER_ID = "me";
+export const GMAIL_MAX_RETRIES = 3;
+const GMAIL_BASE_BACKOFF_MS = 1000;
+const GMAIL_MAX_BACKOFF_MS = 30_000;
+/** Gateway calls one fetch may make, retries included, before it stops with the cursor unmoved. */
+export const GMAIL_MAX_REQUESTS_PER_FETCH = 1000;
 function nonEmptyString(value) {
     return typeof value === "string" && value.trim() !== "" ? value : undefined;
 }
@@ -168,6 +186,17 @@ function isRateLimited(err) {
         return true;
     return err instanceof Error && RATE_LIMIT_PATTERN.test(err.message);
 }
+function retryAfterMs(err) {
+    const e = err;
+    let raw = e?.retryAfter;
+    if (raw === undefined && e?.headers && typeof e.headers === "object") {
+        const h = e.headers;
+        raw = typeof h.get === "function" ? h.get("retry-after") : (h["retry-after"] ?? h["Retry-After"]);
+    }
+    const secs = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : NaN;
+    return Number.isFinite(secs) && secs >= 0 ? secs * 1000 : null;
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function parseWatch(result, now) {
     const body = unwrapResult(result);
     if (!isRecord(body))
@@ -323,10 +352,35 @@ function toEvent(change, headers, personUid, now) {
 export function createGmailAdapter(options = {}) {
     const pageSize = Math.min(MAX_PAGE_SIZE, Math.max(1, Math.floor(options.pageSize ?? DEFAULT_PAGE_SIZE)));
     const clock = options.now ?? (() => new Date());
+    const sleep = options.sleep ?? defaultSleep;
     async function fetch(cursor, ctx) {
-        const gateway = ctx.gateway;
-        if (!gateway)
+        const gw = ctx.gateway;
+        if (!gw)
             throw new Error("Gmail hot channel needs a gateway connection");
+        let requests = 0;
+        // Every call is scoped to userId "me" and retries 429s with backoff. A
+        // persistent 429 or the per-fetch request cap throws before any cursor
+        // is returned, so the watermark does not move.
+        const gateway = {
+            async call(tool, args) {
+                for (let attempt = 0;; attempt++) {
+                    if (requests >= GMAIL_MAX_REQUESTS_PER_FETCH)
+                        throw new GmailRateLimitedError(null);
+                    requests++;
+                    try {
+                        return await gw.call(tool, { ...args, userId: GMAIL_USER_ID });
+                    }
+                    catch (err) {
+                        if (isAuthFailure(err) || !isRateLimited(err))
+                            throw err;
+                        const wait = retryAfterMs(err);
+                        if (attempt >= GMAIL_MAX_RETRIES)
+                            throw new GmailRateLimitedError(wait);
+                        await sleep(Math.min(GMAIL_MAX_BACKOFF_MS, wait ?? GMAIL_BASE_BACKOFF_MS * 2 ** attempt));
+                    }
+                }
+            },
+        };
         const now = clock();
         const state = parseGmailCursor(cursor);
         let watch = null;
@@ -399,6 +453,9 @@ export function createGmailAdapter(options = {}) {
     }
     return {
         id: GMAIL_ADAPTER_ID,
+        displayName: "Gmail",
+        provider: GMAIL_PROVIDER,
+        watermarkKind: "cursor",
         channel: GMAIL_CHANNEL,
         transport: "poll",
         hotEventTypes: [GMAIL_MESSAGE_ADDED_EVENT, GMAIL_LABEL_ADDED_EVENT],

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

@@ -34,6 +34,17 @@
  * A revoked or expired token (`invalid_grant`) surfaces from the gateway call;
  * run.ts turns it into a reconnect prompt in the run ledger and the cursor
  * does not move.
+ *
+ * A rate-limited call (HTTP 429, or a rate-limit error from the gateway) is
+ * retried up to `LINEAR_MAX_RETRIES` times, waiting for `Retry-After` when the
+ * error carries one (capped) or an exponential backoff otherwise. When the
+ * retries run out the fetch throws `LinearRateLimitedError`, so the run fails,
+ * nothing lands for that page and the cursor does not move.
+ *
+ * Request budget: a run makes at most `DEFAULT_MAX_PAGES_PER_ADAPTER` (20)
+ * pages, each at most `1 + LINEAR_MAX_RETRIES` requests, so
+ * `LINEAR_MAX_REQUESTS_PER_RUN` is 60. 41 worst-case runs in one hour still
+ * stay under `LINEAR_REQUESTS_PER_HOUR` (2,500).
  */
 import { type PollHotChannelAdapter } from "../contract.js";
 export declare const LINEAR_ADAPTER_ID = "linear";
@@ -44,10 +55,23 @@ export declare const LINEAR_LIST_ISSUES_TOOL = "list_issues";
 /** Linear's request budget for one personal token. */
 export declare const LINEAR_REQUESTS_PER_HOUR = 2500;
 export declare const LINEAR_CATCH_UP_WINDOW_MS: number;
+/** Retries for one rate-limited `list_issues` call before the run gives up. */
+export declare const LINEAR_MAX_RETRIES = 2;
+/** Most requests one run can make: every page, every retry. */
+export declare const LINEAR_MAX_REQUESTS_PER_RUN: number;
 export declare const LINEAR_ISSUE_FIELDS: readonly ["id", "uuid", "title", "priority", "url", "createdAt", "updatedAt", "completedAt", "dueDate", "status", "statusType", "labels", "assignee", "project", "team"];
 export interface LinearAdapterOptions {
     /** Issues per `list_issues` call. Clamped to 1..250. Default 100. */
     pageSize?: number;
+    /** Waits between rate-limit retries. Tests pass a fake. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Linear kept answering 429 after every retry; the cursor stays put. */
+export declare class LinearRateLimitedError extends Error {
+    readonly retryAfterMs: number | null;
+    readonly code = "rate_limited";
+    readonly status = 429;
+    constructor(retryAfterMs: number | null);
 }
 /** The adapter's cursor: see the file comment. */
 export interface LinearCursor {