@indigoai-us/hq-cli 5.345.178 → 5.345.179

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

@@ -0,0 +1,81 @@
+/**
+ * Meetings hot channel (hot-signal-sync US-008).
+ *
+ * Reads meeting transcripts already in the company vault under
+ * `sources/meetings/` and emits one event per transcript the signed-in person
+ * attended. It needs no connection: the catalog item names provider
+ * `hq-vault`, and run.ts calls it once with no gateway.
+ *
+ * Each landed document is a pointer, not a copy. Its body is a short header
+ * (title, when, who, audience, where) and `payload_ref` names the original
+ * transcript. The `.raw.json` sidecar holds the transcript frontmatter and the
+ * audience, never the transcript segments.
+ *
+ * `audience_source` on the landed document says how the audience was derived:
+ * `sidecar` (the attendee list in `{id}.audience[.vN].json`), `frontmatter`
+ * (an `attendees` or `audience` list on the transcript) or `person_uid` (only
+ * the person who captured the meeting).
+ *
+ * Fireflies and Granola (owner, 2026-10-29: "especially for a new user ...
+ * they won't have our meetings bot yet so we need to use those providers").
+ * One Meetings channel reads every source: the vault (HQ bot) plus each usable
+ * Fireflies or Granola connection, which run.ts hands over as
+ * `PollContext.gateways` (`companionProviders`). For a provider meeting the
+ * adapter writes the provider's notes and transcript verbatim to
+ * `sources/meeting-notes/{provider}/{id}.md` and lands a pointer to it, with
+ * `provider` set on the landed document. A provider meeting that matches a bot
+ * transcript, or a meeting already written by another provider, is skipped
+ * (same calendar event, or starts within 30 minutes plus the same link, title
+ * or most participants), so one meeting yields one set of signals. The reverse
+ * order holds too: a bot transcript arriving after one of this person's
+ * provider connections already landed the same meeting is skipped, so the
+ * meeting keeps one pointer and its signals do not run twice. Only notes
+ * written by the person's own connections count for either check.
+ *
+ * The cursor is the vault cursor (an ISO time) while no provider is
+ * connected. With providers it is JSON `{ vault, providers: { [connectionId]:
+ * watermark } }`; each provider watermark is the start of the newest meeting
+ * handled. A connection's first sync backfills the last 14 days, newest 50
+ * meetings at most, so onboarding produces signals on the first run. A
+ * meeting from the last 3 hours with no notes yet is left for the next run.
+ * A provider that fails (revoked token, outage) is warned about and keeps its
+ * watermark; the vault and other providers still land.
+ */
+import { type PollHotChannelAdapter } from "../contract.js";
+export declare const MEETINGS_ADAPTER_ID = "meetings";
+export declare const MEETINGS_CHANNEL = "meeting-events";
+export declare const MEETINGS_PROVIDER = "hq-vault";
+export declare const MEETING_TRANSCRIPT_EVENT = "meeting.transcript";
+export declare const MEETINGS_TRANSCRIPT_DIR = "sources/meetings";
+export declare const MEETING_NOTES_DIR = "sources/meeting-notes";
+/** Provider set on landed documents for bot transcripts read from the vault. */
+export declare const MEETINGS_VAULT_SOURCE = "hq-vault";
+/** First sync of a provider connection reaches back this far. */
+export declare const MEETINGS_BACKFILL_MS: number;
+/** ... and lands at most this many meetings. */
+export declare const MEETINGS_BACKFILL_MAX = 50;
+export type MeetingAudienceSource = "sidecar" | "frontmatter" | "person_uid";
+export interface MeetingsAdapterOptions {
+    /** Company vault root (`companies/{company}`). */
+    vaultRoot: string;
+    /**
+     * The signed-in person's identities besides `ctx.personUid`: their `prs_`
+     * person uid and email. A transcript is emitted only when its audience
+     * contains one of them. Compared case-insensitively.
+     */
+    identities?: readonly string[];
+    /** Transcripts newer than the cursor per page. Default 100. */
+    pageSize?: number;
+    /** Clock for the backfill and settle windows. Default: the run's `since` plus the catch-up window. */
+    now?: () => number;
+    /** Where a failing provider is reported. Default: a line on stderr. */
+    warn?: (message: string) => void;
+}
+/** The adapter cursor: see the file comment. */
+export interface MeetingsCursor {
+    vault: string | null;
+    providers: Record<string, string>;
+}
+export declare function parseMeetingsCursor(cursor: string | null): MeetingsCursor;
+export declare function createMeetingsAdapter(options: MeetingsAdapterOptions): PollHotChannelAdapter;
+//# sourceMappingURL=meetings.d.ts.map

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

@@ -0,0 +1,523 @@
+/**
+ * Meetings hot channel (hot-signal-sync US-008).
+ *
+ * Reads meeting transcripts already in the company vault under
+ * `sources/meetings/` and emits one event per transcript the signed-in person
+ * attended. It needs no connection: the catalog item names provider
+ * `hq-vault`, and run.ts calls it once with no gateway.
+ *
+ * Each landed document is a pointer, not a copy. Its body is a short header
+ * (title, when, who, audience, where) and `payload_ref` names the original
+ * transcript. The `.raw.json` sidecar holds the transcript frontmatter and the
+ * audience, never the transcript segments.
+ *
+ * `audience_source` on the landed document says how the audience was derived:
+ * `sidecar` (the attendee list in `{id}.audience[.vN].json`), `frontmatter`
+ * (an `attendees` or `audience` list on the transcript) or `person_uid` (only
+ * the person who captured the meeting).
+ *
+ * Fireflies and Granola (owner, 2026-10-29: "especially for a new user ...
+ * they won't have our meetings bot yet so we need to use those providers").
+ * One Meetings channel reads every source: the vault (HQ bot) plus each usable
+ * Fireflies or Granola connection, which run.ts hands over as
+ * `PollContext.gateways` (`companionProviders`). For a provider meeting the
+ * adapter writes the provider's notes and transcript verbatim to
+ * `sources/meeting-notes/{provider}/{id}.md` and lands a pointer to it, with
+ * `provider` set on the landed document. A provider meeting that matches a bot
+ * transcript, or a meeting already written by another provider, is skipped
+ * (same calendar event, or starts within 30 minutes plus the same link, title
+ * or most participants), so one meeting yields one set of signals. The reverse
+ * order holds too: a bot transcript arriving after one of this person's
+ * provider connections already landed the same meeting is skipped, so the
+ * meeting keeps one pointer and its signals do not run twice. Only notes
+ * written by the person's own connections count for either check.
+ *
+ * The cursor is the vault cursor (an ISO time) while no provider is
+ * connected. With providers it is JSON `{ vault, providers: { [connectionId]:
+ * watermark } }`; each provider watermark is the start of the newest meeting
+ * handled. A connection's first sync backfills the last 14 days, newest 50
+ * meetings at most, so onboarding produces signals on the first run. A
+ * meeting from the last 3 hours with no notes yet is left for the next run.
+ * A provider that fails (revoked token, outage) is warned about and keeps its
+ * watermark; the vault and other providers still land.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { isAuthError } from "../../../utils/auth-error.js";
+import { MAX_CATCH_UP_WINDOW_MS } from "../contract.js";
+import { assertSafeSegment, HOT_SIGNAL_ORIGIN, writeFileAtomic } from "../landing.js";
+import { MEETING_NOTE_PROVIDERS, MEETING_PROVIDERS, sameMeeting, } from "./meeting-providers.js";
+export const MEETINGS_ADAPTER_ID = "meetings";
+export const MEETINGS_CHANNEL = "meeting-events";
+export const MEETINGS_PROVIDER = "hq-vault";
+export const MEETING_TRANSCRIPT_EVENT = "meeting.transcript";
+export const MEETINGS_TRANSCRIPT_DIR = "sources/meetings";
+export const MEETING_NOTES_DIR = "sources/meeting-notes";
+/** Provider set on landed documents for bot transcripts read from the vault. */
+export const MEETINGS_VAULT_SOURCE = "hq-vault";
+/** First sync of a provider connection reaches back this far. */
+export const MEETINGS_BACKFILL_MS = 14 * 24 * 60 * 60 * 1000;
+/** ... and lands at most this many meetings. */
+export const MEETINGS_BACKFILL_MAX = 50;
+/** Provider meetings read per connection per fetch. */
+const PROVIDER_PAGE_SIZE = 10;
+/** A meeting this recent with no notes yet may still be processing. */
+const SETTLE_MS = 3 * 60 * 60 * 1000;
+const DEFAULT_PAGE_SIZE = 100;
+/** A gateway reconnect, an HQ auth error, or an HTTP 401/403 from a provider call. */
+function isProviderAuthFailure(err) {
+    if (err?.code === "HOT_CHANNEL_RECONNECT_REQUIRED")
+        return true;
+    if (isAuthError(err))
+        return true;
+    const status = err?.status;
+    return status === 401 || status === 403;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+function stringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.map(nonEmptyString).filter((v) => v !== undefined))];
+}
+function toVersion(value) {
+    const n = typeof value === "string" ? Number(value) : value;
+    return typeof n === "number" && Number.isInteger(n) && n >= 0 ? n : 0;
+}
+/** Split `---\n{yaml}\n---\n{body}`. Unparseable or non-object frontmatter is null. */
+function splitFrontmatter(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;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    return { frontmatter: parsed, body: text.slice(match[0].length) };
+}
+async function readJson(file) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The audience sidecar with the highest `audienceVersion`, when it lists anyone. */
+async function readSidecarAudience(dir, base, names) {
+    const pattern = new RegExp(`^${base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\.audience(?:\\.v\\d+)?\\.json$`);
+    let best = null;
+    for (const name of [...names].filter((n) => pattern.test(n)).sort()) {
+        const doc = await readJson(path.join(dir, name));
+        if (!doc)
+            continue;
+        const audience = [...new Set([...stringList(doc.invitedMemberUids), ...stringList(doc.unresolvedInvitedEmails)])];
+        const version = toVersion(doc.audienceVersion);
+        if (audience.length > 0 && (!best || version > best.version))
+            best = { audience, version };
+    }
+    return best;
+}
+async function readTranscript(dir, file, names) {
+    let text;
+    try {
+        text = await fs.readFile(path.join(dir, file), "utf8");
+    }
+    catch {
+        return null;
+    }
+    const split = splitFrontmatter(text);
+    if (!split)
+        return null;
+    const fm = split.frontmatter;
+    if (fm.origin === HOT_SIGNAL_ORIGIN)
+        return null;
+    const title = nonEmptyString(fm.title);
+    const transcriptId = nonEmptyString(fm.transcript_id) ?? nonEmptyString(fm.id) ?? nonEmptyString(fm.source_id);
+    const stamp = nonEmptyString(fm.updated_at) ?? nonEmptyString(fm.ingested_at) ?? nonEmptyString(fm.created_at);
+    const tsMs = stamp === undefined ? NaN : Date.parse(stamp);
+    if (!title || !transcriptId || Number.isNaN(tsMs))
+        return null;
+    const base = file.slice(0, -".md".length);
+    const sidecar = await readSidecarAudience(dir, base, names);
+    const fmAudience = stringList(fm.attendees).length > 0 ? stringList(fm.attendees) : stringList(fm.audience);
+    const owner = nonEmptyString(fm.person_uid);
+    let audience;
+    let audienceSource;
+    let audienceVersion;
+    if (sidecar) {
+        ({ audience, version: audienceVersion } = sidecar);
+        audienceSource = "sidecar";
+    }
+    else if (fmAudience.length > 0) {
+        audience = fmAudience;
+        audienceSource = "frontmatter";
+        audienceVersion = toVersion(fm.audience_version);
+    }
+    else if (owner) {
+        audience = [owner];
+        audienceSource = "person_uid";
+        audienceVersion = toVersion(fm.audience_version);
+    }
+    else {
+        return null;
+    }
+    return {
+        file,
+        tsMs,
+        transcriptId,
+        frontmatter: fm,
+        bodyDigest: createHash("sha256").update(split.body).digest("hex").slice(0, 12),
+        title,
+        audience,
+        audienceSource,
+        audienceVersion,
+        identity: {
+            startMs: Date.parse(nonEmptyString(fm.scheduled_start_time) ?? "") || tsMs,
+            title,
+            participants: audience.filter((a) => a.includes("@")),
+            ...(nonEmptyString(fm.meeting_url) ? { meetingUrl: nonEmptyString(fm.meeting_url) } : {}),
+            ...(nonEmptyString(fm.calendar_event_id) ? { calendarEventId: nonEmptyString(fm.calendar_event_id) } : {}),
+        },
+    };
+}
+function toEvent(t) {
+    const when = new Date(t.tsMs).toISOString();
+    const who = nonEmptyString(t.frontmatter.person_uid) ?? "unknown";
+    const where = nonEmptyString(t.frontmatter.meeting_platform) ?? "meeting";
+    const payloadRef = `${MEETINGS_TRANSCRIPT_DIR}/${t.file}`;
+    const body = [
+        `# ${t.title}`,
+        "",
+        `- When: ${when}`,
+        `- Who: ${who}`,
+        `- Audience: ${t.audience.join(", ")}`,
+        `- Where: ${where}`,
+        `- Transcript: ${payloadRef}`,
+        "",
+    ].join("\n");
+    return {
+        providerId: t.transcriptId,
+        version: `${t.audienceVersion}.${t.bodyDigest}`,
+        who,
+        what: MEETING_TRANSCRIPT_EVENT,
+        where,
+        when,
+        audience: [...t.audience],
+        title: t.title,
+        body,
+        payloadRef,
+        frontmatter: { audience_source: t.audienceSource, provider: MEETINGS_VAULT_SOURCE },
+        raw: { transcript: payloadRef, frontmatter: t.frontmatter, audience: [...t.audience], audience_source: t.audienceSource },
+    };
+}
+function byTimeThenName(a, b) {
+    return a.tsMs - b.tsMs || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
+}
+export function parseMeetingsCursor(cursor) {
+    if (cursor === null)
+        return { vault: null, providers: {} };
+    if (!cursor.trimStart().startsWith("{"))
+        return { vault: cursor, providers: {} };
+    try {
+        const parsed = JSON.parse(cursor);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return { vault: null, providers: {} };
+        const rec = parsed;
+        const providers = {};
+        if (rec.providers && typeof rec.providers === "object" && !Array.isArray(rec.providers)) {
+            for (const [id, mark] of Object.entries(rec.providers)) {
+                if (typeof mark === "string" && !Number.isNaN(Date.parse(mark)))
+                    providers[id] = mark;
+            }
+        }
+        return { vault: typeof rec.vault === "string" ? rec.vault : null, providers };
+    }
+    catch {
+        return { vault: null, providers: {} };
+    }
+}
+function serializeMeetingsCursor(cursor) {
+    if (Object.keys(cursor.providers).length === 0)
+        return cursor.vault;
+    return JSON.stringify({ vault: cursor.vault, providers: cursor.providers });
+}
+function safeId(id) {
+    try {
+        assertSafeSegment(id, "meeting id");
+        return id;
+    }
+    catch {
+        return createHash("sha256").update(id).digest("hex").slice(0, 32);
+    }
+}
+async function readNotesDocs(vaultRoot, sinceMs) {
+    const out = [];
+    for (const provider of MEETING_NOTE_PROVIDERS) {
+        const dir = path.join(vaultRoot, MEETING_NOTES_DIR, provider);
+        let names;
+        try {
+            names = await fs.readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names.filter((n) => n.endsWith(".md"))) {
+            let text;
+            try {
+                text = await fs.readFile(path.join(dir, name), "utf8");
+            }
+            catch {
+                continue;
+            }
+            const fm = splitFrontmatter(text)?.frontmatter;
+            const start = fm ? Date.parse(nonEmptyString(fm.meeting_start) ?? "") : NaN;
+            const id = fm ? nonEmptyString(fm.provider_meeting_id) : undefined;
+            if (!fm || !id || Number.isNaN(start) || start < sinceMs - MEETINGS_BACKFILL_MS)
+                continue;
+            out.push({
+                provider,
+                id,
+                connectionId: nonEmptyString(fm.connection_id) ?? "",
+                identity: {
+                    startMs: start,
+                    title: nonEmptyString(fm.title) ?? "",
+                    participants: stringList(fm.participants),
+                    ...(nonEmptyString(fm.meeting_url) ? { meetingUrl: nonEmptyString(fm.meeting_url) } : {}),
+                    ...(nonEmptyString(fm.calendar_event_id) ? { calendarEventId: nonEmptyString(fm.calendar_event_id) } : {}),
+                },
+            });
+        }
+    }
+    return out;
+}
+export function createMeetingsAdapter(options) {
+    const dir = path.join(options.vaultRoot, MEETINGS_TRANSCRIPT_DIR);
+    const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+    if (!Number.isInteger(pageSize) || pageSize < 1)
+        throw new Error("meetings pageSize must be a positive integer");
+    const warn = options.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    /** Every parseable bot transcript, and the person's page after the cursor. */
+    async function fetchVault(cursor, ctx) {
+        let names;
+        try {
+            names = await fs.readdir(dir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                return { events: [], cursor, hasMore: false, all: [] };
+            }
+            throw err;
+        }
+        const nameSet = new Set(names);
+        const me = new Set([ctx.personUid, ...(options.identities ?? [])].map((id) => id.toLowerCase()));
+        const sinceMs = Date.parse(ctx.since);
+        const cursorMs = cursor === null ? NaN : Date.parse(cursor);
+        const all = [];
+        const candidates = [];
+        for (const file of names.filter((n) => n.endsWith(".md")).sort()) {
+            const t = await readTranscript(dir, file, nameSet);
+            if (!t || t.tsMs < sinceMs - MEETINGS_BACKFILL_MS)
+                continue;
+            all.push(t);
+            if (t.tsMs < sinceMs)
+                continue;
+            if (!t.audience.some((a) => me.has(a.toLowerCase())))
+                continue;
+            candidates.push(t);
+        }
+        candidates.sort(byTimeThenName);
+        // Transcripts at the cursor time are re-read every page: a transcript that
+        // lands later with the same timestamp is not lost, and duplicates are
+        // dropped by landing. A page never splits one timestamp.
+        const atCursor = candidates.filter((t) => t.tsMs === cursorMs);
+        const newer = Number.isNaN(cursorMs) ? candidates : candidates.filter((t) => t.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 last = page[page.length - 1];
+        return {
+            events: [...atCursor, ...page].map(toEvent),
+            cursor: last ? new Date(last.tsMs).toISOString() : cursor,
+            hasMore: end < newer.length,
+            all,
+        };
+    }
+    async function writeNotes(provider, connectionId, m, text) {
+        const ref = `${MEETING_NOTES_DIR}/${provider.provider}/${safeId(m.id)}.md`;
+        const file = path.resolve(options.vaultRoot, ref);
+        const sourcesRoot = path.resolve(options.vaultRoot, "sources") + path.sep;
+        if (!file.startsWith(sourcesRoot))
+            throw new Error(`meetings: refused to write outside sources/ (${ref})`);
+        const frontmatter = {
+            title: m.title,
+            provider: provider.provider,
+            provider_meeting_id: m.id,
+            connection_id: connectionId,
+            meeting_start: new Date(m.startMs).toISOString(),
+            participants: m.participants,
+            ...(m.organizer ? { organizer: m.organizer } : {}),
+            ...(m.meetingUrl ? { meeting_url: m.meetingUrl } : {}),
+            ...(m.calendarEventId ? { calendar_event_id: m.calendarEventId } : {}),
+            origin: HOT_SIGNAL_ORIGIN,
+        };
+        await writeFileAtomic(file, `---\n${yaml.dump(frontmatter, { lineWidth: -1, noRefs: true }).trimEnd()}\n---\n${text}`);
+        return ref;
+    }
+    function providerEvent(provider, m, ref, text, me) {
+        const when = new Date(m.startMs).toISOString();
+        const audience = m.participants.length > 0 ? [...new Set([me, ...m.participants])] : [me];
+        const who = m.organizer ?? me;
+        const body = [
+            `# ${m.title}`,
+            "",
+            `- When: ${when}`,
+            `- Who: ${who}`,
+            `- Audience: ${audience.join(", ")}`,
+            `- Where: ${provider}`,
+            `- Transcript: ${ref}`,
+            "",
+        ].join("\n");
+        return {
+            providerId: `${provider}:${m.id}`,
+            version: createHash("sha256").update(text).digest("hex").slice(0, 12),
+            who,
+            what: MEETING_TRANSCRIPT_EVENT,
+            where: provider,
+            when,
+            audience,
+            title: m.title,
+            body,
+            payloadRef: ref,
+            frontmatter: { audience_source: "provider", provider },
+            raw: { transcript: ref, provider, meeting: { ...m, start: when }, audience },
+        };
+    }
+    /** One page of one provider connection. Returns its events and new watermark. */
+    async function fetchProvider(gateway, provider, watermark, ctx, known, notes) {
+        const nowMs = options.now ? options.now() : Date.parse(ctx.since) + MAX_CATCH_UP_WINDOW_MS;
+        const firstRun = watermark === undefined;
+        const fromMs = firstRun
+            ? Math.max(Date.parse(ctx.since), nowMs - MEETINGS_BACKFILL_MS)
+            : Math.max(Date.parse(watermark), Date.parse(ctx.since));
+        let listed = (await provider.list(gateway, fromMs, nowMs)).filter((m) => firstRun || m.startMs > fromMs);
+        if (firstRun && listed.length > MEETINGS_BACKFILL_MAX)
+            listed = listed.slice(-MEETINGS_BACKFILL_MAX);
+        const me = new Set([ctx.personUid, ...(options.identities ?? [])].map((id) => id.toLowerCase()));
+        const emails = [...me].filter((id) => id.includes("@"));
+        const events = [];
+        let mark = watermark;
+        let deduped = 0;
+        let processed = 0;
+        for (const m of listed) {
+            if (processed >= PROVIDER_PAGE_SIZE)
+                break;
+            // The person's own connection lists what they can see; keep meetings
+            // they were in when their email is known.
+            const mine = emails.length === 0 ||
+                m.participants.length === 0 ||
+                m.participants.some((p) => me.has(p)) ||
+                (m.organizer !== undefined && me.has(m.organizer));
+            const sameAsKnown = known.some((k) => sameMeeting(k, m));
+            const sameAsOther = notes.some((n) => !(n.provider === provider.provider && n.id === m.id) && sameMeeting(n.identity, m));
+            if (!mine || sameAsKnown || sameAsOther) {
+                if (mine)
+                    deduped += 1;
+                mark = new Date(m.startMs).toISOString();
+                continue;
+            }
+            processed += 1;
+            const content = await provider.read(gateway, m);
+            // read() may fill in the calendar event id; check again with it.
+            if (known.some((k) => sameMeeting(k, m)) || notes.some((n) => !(n.provider === provider.provider && n.id === m.id) && sameMeeting(n.identity, m))) {
+                deduped += 1;
+                mark = new Date(m.startMs).toISOString();
+                continue;
+            }
+            if (!content.hasContent) {
+                if (nowMs - m.startMs < SETTLE_MS)
+                    break;
+                mark = new Date(m.startMs).toISOString();
+                continue;
+            }
+            const ref = await writeNotes(provider, gateway.connectionId, m, content.text);
+            notes.push({ provider: provider.provider, id: m.id, connectionId: gateway.connectionId, identity: m });
+            events.push(providerEvent(provider.provider, m, ref, content.text, ctx.personUid));
+            mark = new Date(m.startMs).toISOString();
+        }
+        const markMs = mark === undefined ? NaN : Date.parse(mark);
+        const hasMore = listed.some((m) => Number.isNaN(markMs) || m.startMs > markMs) && processed >= PROVIDER_PAGE_SIZE;
+        // A first run that found nothing still records where it looked from.
+        return { events, watermark: mark ?? new Date(fromMs).toISOString(), hasMore, deduped };
+    }
+    async function fetch(cursor, ctx) {
+        const state = parseMeetingsCursor(cursor);
+        const vault = await fetchVault(state.vault, ctx);
+        const gateways = (ctx.gateways ?? []).filter((g) => MEETING_PROVIDERS.has(g.provider.toLowerCase()));
+        // Provider notes this person's own connections wrote (current connections,
+        // or any connection this cursor holds a watermark for). A teammate's notes
+        // never suppress this person's meetings.
+        const ownConnections = new Set([...gateways.map((g) => g.connectionId), ...Object.keys(state.providers)]);
+        const notes = ownConnections.size > 0
+            ? (await readNotesDocs(options.vaultRoot, Date.parse(ctx.since))).filter((n) => ownConnections.has(n.connectionId))
+            : [];
+        // A bot transcript for a meeting a provider already landed is skipped:
+        // one pointer per meeting, and its signals already ran.
+        const vaultEvents = vault.events.filter((e) => {
+            const t = vault.all.find((x) => x.transcriptId === e.providerId);
+            return !t || !notes.some((n) => sameMeeting(n.identity, t.identity));
+        });
+        if (vaultEvents.length < vault.events.length) {
+            warn(`meetings: skipped ${vault.events.length - vaultEvents.length} bot transcript(s) already captured by a meeting provider`);
+        }
+        const events = [...vaultEvents];
+        let hasMore = vault.hasMore;
+        const next = { vault: vault.cursor, providers: { ...state.providers } };
+        if (gateways.length > 0) {
+            const known = vault.all.map((t) => t.identity);
+            for (const gateway of gateways) {
+                const provider = MEETING_PROVIDERS.get(gateway.provider.toLowerCase());
+                try {
+                    const page = await fetchProvider(gateway, provider, state.providers[gateway.connectionId], ctx, known, notes);
+                    events.push(...page.events);
+                    if (page.watermark !== undefined)
+                        next.providers[gateway.connectionId] = page.watermark;
+                    hasMore = hasMore || page.hasMore;
+                    if (page.deduped > 0)
+                        warn(`meetings: ${provider.provider} ${gateway.connectionId}: skipped ${page.deduped} meeting(s) already captured by another source`);
+                }
+                catch (err) {
+                    // A sign-in or revoked connection must reach run.ts so the ledger
+                    // records the reconnect; only other provider errors are swallowed.
+                    if (isProviderAuthFailure(err))
+                        throw err;
+                    warn(`meetings: ${provider.provider} ${gateway.connectionId} failed; its watermark stays put: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        return { events, cursor: serializeMeetingsCursor(next), hasMore };
+    }
+    return {
+        id: MEETINGS_ADAPTER_ID,
+        channel: MEETINGS_CHANNEL,
+        transport: "poll",
+        hotEventTypes: [MEETING_TRANSCRIPT_EVENT],
+        catchUpWindow: { maxLookbackMs: MAX_CATCH_UP_WINDOW_MS },
+        tokenScope: { provider: MEETINGS_PROVIDER, scopes: [] },
+        companionProviders: MEETING_NOTE_PROVIDERS,
+        // Recurring meetings the person attended in the last 30 days.
+        suggestionRule: { kind: "recent-activity", withinMs: MAX_CATCH_UP_WINDOW_MS, minEvents: 2 },
+        fetch,
+    };
+}
+//# sourceMappingURL=meetings.js.map

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

@@ -0,0 +1,70 @@
+/**
+ * Slack hot channel (hot-signal-sync US-006).
+ *
+ * The live Slack events webhook in hq-pro-agents
+ * (`src/sources/inbound/slack-events.ts`) already lands one document per
+ * thread in the company vault under `sources/slack/`. From the local loop's
+ * side those threads are in the vault before the sync starts, so this adapter
+ * is a poll adapter over that folder, the same shape as meetings (US-008). It
+ * lists the thread documents ingested after the cursor that belong to the
+ * signed-in person, oldest first, and the cursor is the newest `ingested_at`.
+ *
+ * The hq-pro catalog entry for slack still says `transport: push`. run.ts
+ * plans by the registered adapter's transport, so this adapter runs once per
+ * usable Slack connection either way; the catalog correction is an hq-pro
+ * follow-up.
+ *
+ * Each landed document is a pointer. Its body is a short header (channel,
+ * time, owner, message count, audience) and `payload_ref` names the thread
+ * document. No message text is copied: the `.raw.json` sidecar holds only
+ * thread metadata.
+ *
+ * `audience_source` says how the audience was derived: `channel_members` (a
+ * `channel_members` or `audience` list on the thread document) or
+ * `person_uid` (only the person whose connection landed the thread). Today's
+ * writer records no channel membership, so the audience is the person until it
+ * does. The Slack user ids of the people in the thread are kept as
+ * `slack_participants`.
+ *
+ * Slack pauses event delivery to an app that exceeds its rate limit and sends
+ * `app_rate_limited`. A marker newer than the cursor (`_app_rate_limited.json`
+ * or a document with `type: app_rate_limited` in `sources/slack/`, without a
+ * `resolved_at`) fails the adapter with `SlackAppRateLimitedError`, whose
+ * message lands in the run ledger's `error`. The cursor does not move.
+ * Writing that marker from the webhook is an hq-pro-agents follow-up.
+ */
+import { type PollHotChannelAdapter } from "../contract.js";
+export declare const SLACK_ADAPTER_ID = "slack";
+export declare const SLACK_CHANNEL = "slack-events";
+export declare const SLACK_PROVIDER = "slack";
+export declare const SLACK_THREAD_EVENT = "slack.thread";
+export declare const SLACK_THREAD_DIR = "sources/slack";
+export declare const SLACK_RATE_LIMIT_MARKER = "_app_rate_limited.json";
+export declare const SLACK_APP_RATE_LIMITED = "app_rate_limited";
+export type SlackAudienceSource = "channel_members" | "person_uid";
+/** Slack paused event delivery, so threads after `pausedAt` may be missing. */
+export declare class SlackAppRateLimitedError extends Error {
+    readonly pausedAt: string;
+    readonly code = "app_rate_limited";
+    constructor(pausedAt: string);
+}
+export interface SlackAdapterOptions {
+    /** Company vault root (`companies/{company}`). */
+    vaultRoot: string;
+    /**
+     * The signed-in person's identities besides `ctx.personUid`: their `prs_`
+     * person uid and email. A thread is the person's when its `person_uid` is
+     * one of them. Compared case-insensitively.
+     */
+    identities?: readonly string[];
+    /**
+     * The person's Slack account ids (`slk_...`). A thread is also the person's
+     * when its `account_id` is one of them. The run's connection id is checked
+     * the same way.
+     */
+    accountIds?: readonly string[];
+    /** Threads newer than the cursor per page. Default 100. */
+    pageSize?: number;
+}
+export declare function createSlackAdapter(options: SlackAdapterOptions): PollHotChannelAdapter;
+//# sourceMappingURL=slack.d.ts.map