@open-everywhere/provider-notion 0.1.0

package/agent/channels/notion-engagement.ts

@@ -0,0 +1,372 @@
+// THE NOTION AMBIENT ENGAGEMENT SEAM (chat-surface contract §2.5) — the Notion wiring over core's
+// pure engagement policy (`packages/core/agent/channels/engagement.ts`). It gives Notion the middle
+// posture Slack, Discord and Teams already have: addressing the app marks the PAGE ENGAGED, a later
+// PLAIN comment on that page wakes the agent, and `stand_down` stores the stop.
+//
+// THE ANCHOR is `notionConversationKey(workspaceId, pageId)` — `<workspace>/<page>`, the same string
+// the mapper publishes as `anchorChannelId` for the stop registry. The doc session is PAGE-scoped
+// (`notionSupervisorToken` keys the standing session by page, aware of all the page's discussions),
+// so the page is the conversation a person can address a stop to, and a per-discussion mark would
+// leave the same session answering the discussion next door.
+//
+// 🔴 THE ADDRESS IS A NAME-DROP, NOT AN @MENTION, AND THAT IS A VENDOR FACT. Notion lets no user
+// @mention an internal integration at all, so `classifyNotionComment` promotes a name-drop (or the
+// structurally-unreachable structured mention) to `direct` — that IS Notion's addressed leg, and it
+// is therefore what enrols a page here. `notionNameDrop` owns the matching, including its
+// word-boundary guards; this module never looks at comment text.
+
+import {
+  getOperationalStore,
+  getThreadEngagement,
+  markThreadEngaged,
+  resolvePartition,
+  shouldDeliverReply,
+  type EngagementRow,
+  type Partition,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { buildNotionAuth, notionConversationKey } from "./notion-identity.js";
+// TYPE ONLY — it erases, so the "this module imports only notion-identity.ts and core" note above
+// `markNotionEngaged`'s use in notion-supervisor.ts still holds and no cycle is added.
+import type { NotionVia } from "./notion-scope.js";
+
+/** The facts one Notion delivery contributes to the seam — everything the anchor and the partition
+ *  need, and nothing about the comment's text. */
+export interface NotionSeamFacts {
+  readonly workspaceId: string | undefined;
+  readonly pageId: string | undefined;
+  /** The acting Notion user, so the partition the seam keys is built from the delivery's identity. */
+  readonly principalId?: string;
+  /** The integration this delivery verified under — carried for binding parity with the wake. */
+  readonly credentialId?: string;
+}
+
+/** The engagement-registry anchor for one Notion delivery, or `undefined` when either id is missing.
+ *
+ *  🔴 IT IS THE ONE PREDICATE THE MAPPER AND THE SEAM SHARE. `bindNotion` publishes exactly this as
+ *  `engagementKey`, so `stand_down`'s mark and this seam's read address the same row. */
+export function notionEngagementAnchor(f: NotionSeamFacts): string | undefined {
+  return notionConversationKey(f.workspaceId, f.pageId);
+}
+
+/** The partition one page's engagement row lives in — `notion/<workspace>/<page>`, which is what
+ *  `resolvePartition` gives a bound Notion session and therefore what `stand_down` writes under. It
+ *  is built through the same `buildNotionAuth` the wake dispatches, so the seam can never key a row
+ *  the turn would not. Null on an unresolvable identity — the caller then keeps today's path. */
+export function notionSeamPartition(f: NotionSeamFacts): Partition | null {
+  if (!f.workspaceId || !f.pageId) return null;
+  try {
+    const auth = buildNotionAuth({
+      workspaceId: f.workspaceId,
+      pageId: f.pageId,
+      ...(f.principalId ? { principalId: f.principalId } : {}),
+      ...(f.credentialId ? { credentialId: f.credentialId } : {}),
+    });
+    return resolvePartition({ channel: { kind: "notion" }, session: { auth: { current: auth } } });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What the seam says about one comment the classifier did NOT call `direct`. Three outcomes, each
+ * naming what the CALLER owes:
+ *
+ *  • `unanchored` — the delivery names no page (or no resolvable partition), so there is no row to
+ *    address and the caller keeps today's path exactly.
+ *  • `deliver` — a plain comment on an engaged page. The caller wakes a turn even where the page's
+ *    domain has not opted into the ambient supervisor: somebody addressed the agent on THIS page.
+ *  • `hold` — the seam does not admit it. `stopped` says WHY, and it is the one field a caller must
+ *    branch on: `stopped: true` means the agent was asked to stand down on this page, so the comment
+ *    must be SUPPRESSED outright — including where the ambient supervisor is enabled and would
+ *    otherwise answer. `stopped: false` means the page simply is not engaged, which is not a
+ *    suppression: the caller keeps today's path (the domain opt-in then decides).
+ */
+export type NotionEngagementVerdict =
+  | { readonly kind: "unanchored"; readonly reason: string }
+  | { readonly kind: "deliver"; readonly anchor: string; readonly reason: string }
+  | { readonly kind: "hold"; readonly anchor: string; readonly reason: string; readonly stopped: boolean };
+
+/** Injectable seams so the whole verdict is unit-tested without a store. */
+export interface NotionEngagementDeps {
+  readonly getEngagement?: (p: Partition, anchor: string) => Promise<EngagementRow | null>;
+  readonly markEngaged?: (p: Partition, anchor: string, atIso: string) => Promise<void>;
+  /** The durable once-guard BOTH this module's guards take — the engage mark
+   *  ({@link markNotionEngaged}) and the wake ({@link firstNotionDispatchOfComment}). They key on
+   *  different prefixes, so one injected stub serves both. Injected so a test can drive a
+   *  redelivered comment without an operational store. */
+  readonly markEventSeen?: (org: string, key: string, atIso: string) => Promise<boolean>;
+  readonly now?: () => string;
+}
+
+/**
+ * Resolve the seam for one NON-ADDRESSED comment — READ-ONLY. An addressed comment never reaches
+ * this function: it marks instead ({@link markNotionEngaged}), so exactly one caller writes the row.
+ *
+ * THE DECISION ITSELF IS CORE'S. `shouldDeliverReply` owns the disqualifier order and the reasons;
+ * this function only translates Notion facts into its input. Nothing here re-states the policy.
+ *
+ * FAIL-CLOSED on a store error: `getThreadEngagement` reads a failure as `null`, so an unreadable
+ * registry holds rather than delivers.
+ *
+ * `authorIsBot` is the caller's own loop-guard verdict. The classifier drops a self-authored or
+ * integration-authored comment before this runs, so it is `false` on every live call; it stays a
+ * parameter rather than a hard-coded literal so the guard is visible at the call site and a test can
+ * drive the other direction.
+ */
+export async function resolveNotionEngagement(
+  f: NotionSeamFacts,
+  authorIsBot: boolean,
+  deps: NotionEngagementDeps = {},
+): Promise<NotionEngagementVerdict> {
+  const anchor = notionEngagementAnchor(f);
+  if (!anchor) return { kind: "unanchored", reason: "the delivery names no workspace and page — no row to address" };
+  const partition = notionSeamPartition(f);
+  if (!partition) return { kind: "unanchored", reason: "the delivery has no resolvable partition — no row to address" };
+
+  const read = deps.getEngagement ?? ((p, key) => getThreadEngagement(p, key));
+  const row = await read(partition, anchor);
+  const decision = shouldDeliverReply({
+    isEngaged: row !== null,
+    stopped: row?.stopped ?? false,
+    authorIsBot,
+    isAppMention: false, // an addressed comment never reaches this function
+    inThread: true, // an anchored Notion page IS the container engagement is kept per
+  });
+  if (decision.deliver) return { kind: "deliver", anchor, reason: decision.reason };
+  return { kind: "hold", anchor, reason: decision.reason, stopped: row?.stopped === true };
+}
+
+/**
+ * Mark one page ENGAGED on an addressed (name-drop or structured-mention) comment. ONCE PER COMMENT.
+ *
+ * `participating: true` is the re-invitation: it promotes the row and CLEARS a previous stand-down,
+ * which is what "name the agent to bring it back" means here.
+ *
+ * 🔴 THE MARK IS DEDUPED, AND THE STOP IS WHY — the same durable guard GitHub's and Linear's marks
+ * take. Clearing the flag is right for a person's second name-drop and WRONG for Notion redelivering
+ * the first one. THE ROUTE DOES NOT ALWAYS ACK, so the redelivery is reachable: `handleNotionDelivery`
+ * carries no top-level `catch`, and eve's channel dispatcher answers a throw with a 500 — while this
+ * mark sits ABOVE `getOrCreateSession` and the wake, either of which can throw on a store outage. The
+ * sequence that costs is then: name-drop marks the page, the mint throws, Notion is told 500, somebody
+ * asks the agent to stand down, and Notion's retry of the original comment lifts the stop.
+ * `commentId` is the trigger comment's own id, so the guard keys on the thing that must happen once.
+ * DURABLE layer only, and it expires with the store's TTL — a retry later than that window can still
+ * re-mark. FAIL-OPEN on a store error, the posture every dedupe in this repository takes.
+ *
+ * Best-effort throughout — `markThreadEngaged` swallows a store failure, because engagement
+ * bookkeeping must never fail a turn. Returns the anchor it marked, or null when it marked nothing.
+ */
+export async function markNotionEngaged(f: NotionSeamFacts, commentId: string | undefined, deps: NotionEngagementDeps = {}): Promise<string | null> {
+  const anchor = notionEngagementAnchor(f);
+  if (!anchor) return null;
+  const partition = notionSeamPartition(f);
+  if (!partition) return null;
+  const now = deps.now ?? (() => new Date().toISOString());
+  const atIso = now();
+  if (commentId !== undefined && commentId.length > 0) {
+    const seen = deps.markEventSeen ?? liveMarkEngageSeen;
+    if (!(await seen(partition.org, `notion-engage:${anchor}:${commentId}`, atIso))) return null;
+  }
+  const mark = deps.markEngaged ?? ((p, key, at) => markThreadEngaged(p, key, at, { participating: true }));
+  await mark(partition, anchor, atIso);
+  return anchor;
+}
+
+/**
+ * ONE WAKE PER COMMENT (OPE-1906). TRUE = this comment has not woken the agent inside the window,
+ * so the caller should dispatch. FALSE = the same comment id already did, so the caller must not.
+ *
+ * 🔴 THE OTHER HALF OF THE LOOP GUARD, AND THE CLASSIFIER CANNOT BE IT. `classifyNotionComment`
+ * reads one comment's author; a REDELIVERY of a person's comment carries the same author and the
+ * same text, so it classifies identically and dispatches again — a second model turn, a second
+ * `notion.dispatched` row, and a second reply into the discussion. Nothing else on this road is
+ * keyed on the delivery, so this is the only place that can say "again".
+ *
+ * REDELIVERY IS REACHABLE, and {@link markNotionEngaged} above already says why: the route does not
+ * always ack. `handleNotionDelivery` carries no top-level `catch`, and eve's channel dispatcher
+ * answers a throw with a 500, so Notion retries. A page shared with two subscriptions delivers the
+ * same comment twice by design (OPE-467), and a vendor retry needs no failure of ours at all.
+ *
+ * 🔴 THE MARK IS TAKEN BEFORE THE WAKE, AND THAT TRADE IS DELIBERATE. Marking afterwards would let
+ * two concurrent deliveries of one comment both run a turn, which is the cost this guard exists to
+ * stop; `markEventSeen` is atomic across instances, so marking first stops them. The price is that
+ * a delivery whose dispatch THROWS is not retried inside the window — the same price the engage
+ * mark one step above already pays, and the reason this guard sits as LATE as it can, below every
+ * cheaper refusal, so only a delivery that was really about to wake a turn ever spends a mark.
+ *
+ * 🔴 A SUITE THAT DRIVES `handleNotionDelivery` PAST THIS POINT MUST INJECT `markEventSeen`, or
+ * pin its own store path. The default is the DURABLE operational store, and an unpinned suite in
+ * this package shares one sqlite file (scripts/suite-store-isolation-lint.ts says why) — so a suite
+ * that replays a fixed comment id writes a mark that survives the run, and its NEXT run reads
+ * `duplicate-delivery` where it expected `dispatched`. `lint:suite-store` cannot catch that: its
+ * reach test is a source scan, and such a suite names no store entry point of its own. Five suites
+ * inject the stub today.
+ *
+ * FAIL-OPEN, three ways: a store error, an unresolvable partition and a delivery with no comment id
+ * all answer TRUE, so an outage costs a duplicate turn rather than a deaf deployment. The try/catch
+ * covers the INJECTED edge too, not just the live default (the shape webhooks/replay-dedupe.ts and
+ * webhooks/reject-audit.ts take) — which is how a test drives the fail-open arm without breaking a
+ * real store. `commentId` is the thing that must happen once, and a Notion comment id is globally
+ * unique, so the key needs no anchor.
+ */
+export async function firstNotionDispatchOfComment(
+  f: NotionSeamFacts,
+  commentId: string | undefined,
+  deps: NotionEngagementDeps = {},
+): Promise<boolean> {
+  if (commentId === undefined || commentId.length === 0) return true;
+  const partition = notionSeamPartition(f);
+  if (!partition) return true;
+  const now = deps.now ?? (() => new Date().toISOString());
+  const seen = deps.markEventSeen ?? liveMarkDispatchSeen;
+  try {
+    return await seen(partition.org, `notion-dispatch:${commentId}`, now());
+  } catch {
+    return true;
+  }
+}
+
+/** The two addressing values a Notion delivery can carry into a dispatch — `drop` never reaches one. */
+export type NotionDispatchAddressing = "direct" | "channel-watch";
+
+/**
+ * WHAT WOKE ONE ADMITTED DELIVERY, in the wake envelope's own vocabulary (core's `WakeAddressing`).
+ * It is the value the `notion.dispatched` audit row reports, and NO PRODUCT CODE BRANCHES ON IT.
+ * Every reader is an EVIDENCE reader outside the product: the journey pack's `reportedThreadFollow`
+ * (packages/core/scripts/e2e/engaged-rows.ts) gates `J-ENGAGED-notion`'s follow-up step on it,
+ * `drive-notion-namedrop.ts` prints and asserts it, and the test tiers read it. So changing the
+ * value moves what the pack can prove; it moves no delivery decision.
+ *
+ * 🔴 IT IS DELIBERATELY NOT THE CLASSIFIER'S VALUE. The classifier answers one question — did this
+ * comment ADDRESS the agent — and an engaged follow-up did not, so it stays `channel-watch`. The
+ * supervisor core needs that: `channel-watch` is what makes the turn a JUDGED one, and promoting it
+ * would silence the very wake this seam exists to admit.
+ *
+ * 🔴 BUT `channel-watch` ALSO NAMES UNOWNED ROOM CHATTER on an ambient page, and the audit row is
+ * the one place those two must not read alike. A row that reported `channel-watch` for both cannot
+ * tell an ENGAGED wake from an AMBIENT one, and that distinction is the whole evidentiary worth of
+ * the §2.5 seam on this surface: it is what `J-ENGAGED-notion` gates its follow-up step on
+ * (`reportedThreadFollow`, packages/core/scripts/e2e/engaged-rows.ts). Until OPE-1501 the row was
+ * unreachable on an addressed-only page — the ambient gate returned before the classifier ran — so
+ * the collision cost nothing. The gate now admits an engaged follow-up, and the collision costs the
+ * proof, which is what OPE-1510 fixed here.
+ *
+ * 🔴 IT REPORTS THE REGISTRY, NOT THE DOOR. The seam is read for every plain comment, above and
+ * independently of the ambient gate, so on an ambient-ENABLED page a plain comment on an engaged
+ * page also reads `thread-follow` — the ambient flag would have admitted it either way. The value
+ * therefore separates an engaged wake from an ambient one only where the domain has ambient OFF,
+ * which is the addressed-only posture the journeys drive.
+ *
+ * `engagedFollowUp` is the webhook core's own seam verdict, and the `channel-watch` guard below is
+ * belt-and-braces: an ADDRESSED comment never asks the seam, so it can never carry the flag.
+ */
+export function notionWakeAddressing(
+  addressing: NotionDispatchAddressing,
+  engagedFollowUp: boolean | undefined,
+): "direct" | "channel-watch" | "thread-follow" {
+  return addressing === "channel-watch" && engagedFollowUp === true ? "thread-follow" : addressing;
+}
+
+/** The `notion.dispatched` row's two seam fields: what woke the delivery, and how the operator's
+ *  config holds the page. */
+export interface NotionWakeAuditDetail {
+  readonly addressing: "direct" | "channel-watch" | "thread-follow";
+  readonly via: NotionVia;
+}
+
+/**
+ * THE SEAM'S WHOLE CONTRIBUTION TO THE AUDIT ROW, as one pure mapping.
+ *
+ * 🔴 THE TWO FIELDS ANSWER DIFFERENT QUESTIONS, AND A ROW NEEDS BOTH. `addressing` says WHAT WOKE
+ * the delivery. `via` says HOW THE OPERATOR DECLARED THE PAGE, which is the domain origin the
+ * addressed door gated on (`notionPageDomain`, channels/notion-scope.ts). A `container` claim
+ * reaches pages NOBODY ENUMERATED — the whole workspace, or a same-level page glob, which are the
+ * two shapes a container entry may take (memory/domain.ts); a `roster` entry is a page an
+ * operator wrote down. Both reach the same door, and a row carrying only `addressing` reports them
+ * identically — which leaves the wider admission looking exactly like the narrower one in the
+ * audit trail. The row says WHICH KIND of claim, never how wide that claim is: read the domain's
+ * own container entry for the breadth.
+ *
+ * `via` is the webhook core's own read, carried on the dispatch. An absent field reads `none`: the
+ * conservative word, so a caller that omits it can never claim a declaration it did not make.
+ */
+export function notionWakeAuditDetail(
+  addressing: NotionDispatchAddressing,
+  engagedFollowUp: boolean | undefined,
+  via: NotionVia | undefined,
+): NotionWakeAuditDetail {
+  return { addressing: notionWakeAddressing(addressing, engagedFollowUp), via: via ?? "none" };
+}
+
+/** How long this module remembers one comment id — the window both durable guards below key on.
+ *  It bounds the vendor retry both of them answer, so ONE number serves both: a redelivery this
+ *  module treats as "again" for the mark must be "again" for the wake too, or the two guards would
+ *  disagree about the same delivery. */
+const NOTION_DEDUPE_TTL_MS = 10 * 60_000;
+
+/** The durable half of the mark dedupe. FAIL-OPEN: an unreachable store answers "not seen", so a
+ *  store outage costs a redundant mark rather than a lost engagement. */
+let warnedEngageDedupe = false;
+async function liveMarkEngageSeen(org: string, key: string, atIso: string): Promise<boolean> {
+  try {
+    return await getOperationalStore().markEventSeen(org, key, atIso, NOTION_DEDUPE_TTL_MS);
+  } catch (err) {
+    if (!warnedEngageDedupe) {
+      warnedEngageDedupe = true;
+      console.warn(`[open-everywhere:notion-engagement] engage dedupe unavailable — a redelivered name-drop may re-mark: ${String(err)}`);
+    }
+    return true;
+  }
+}
+
+/** The durable half of the WAKE once-guard ({@link firstNotionDispatchOfComment}). Same window as
+ *  the mark above, and the same FAIL-OPEN posture: an unreachable store costs a duplicate turn,
+ *  never a silenced comment. */
+let warnedDispatchDedupe = false;
+async function liveMarkDispatchSeen(org: string, key: string, atIso: string): Promise<boolean> {
+  try {
+    return await getOperationalStore().markEventSeen(org, key, atIso, NOTION_DEDUPE_TTL_MS);
+  } catch (err) {
+    if (!warnedDispatchDedupe) {
+      warnedDispatchDedupe = true;
+      console.warn(`[open-everywhere:notion-engagement] dispatch dedupe unavailable — a redelivered comment may wake a second turn: ${String(err)}`);
+    }
+    return true;
+  }
+}
+
+// ── THE EXACT-JOIN IDS ON THE `notion.dispatched` ROW (OPE-1907) ────────────────────────────────
+
+/** The three ids that let one Notion delivery be joined to the turn it woke. IDS ONLY. */
+export interface NotionDispatchJoinIds {
+  /** The WEBHOOK ENVELOPE's own `id` — unique to this delivery, so two deliveries of the SAME
+   *  comment are tellable apart. Absent when the body carried no id. */
+  readonly deliveryId?: string;
+  /** The TRIGGER COMMENT's id — what the delivery named, and what a replay leg configures. */
+  readonly commentId?: string;
+  /** The single-window wake this delivery minted — the join key `wake.ingress` and
+   *  `wake.turn_start` carry, and therefore the bridge to the session that answered. Absent on a
+   *  per-doc (non-unified) delivery, which mints no window wake. */
+  readonly wakeId?: string;
+}
+
+/**
+ * Build the join ids for the row. Pure, and EVERY FIELD IS AN ID — never a comment body, an author
+ * name or a page title.
+ *
+ * 🔴 WHY THE ROW NEEDS THEM. Before this, `notion.dispatched` recorded the discussion and the
+ * addressing but nothing that identified the DELIVERY, so a leg that forged one replay could only
+ * scan a time window for a verdict row and hope no other wake fell inside it. S-TAINT-DRYRUN Arm B
+ * did exactly that and the scan could not tell its own replay's verdict from an ambient one
+ * (OPE-1907). With the delivery id on the row, one forge joins one wake joins one session.
+ *
+ * An absent value is OMITTED rather than written as `undefined`: an audit row that carries a key
+ * with no value reads, to anyone querying it, like a value that was looked for and found empty.
+ */
+export function notionDispatchJoinDetail(ids: NotionDispatchJoinIds): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (ids.deliveryId) out.deliveryId = ids.deliveryId;
+  if (ids.commentId) out.commentId = ids.commentId;
+  if (ids.wakeId) out.wakeId = ids.wakeId;
+  return out;
+}