@open-everywhere/provider-notion 0.1.0

package/agent/channels/notion-stop.ts

@@ -0,0 +1,169 @@
+// THE NOTION STOP ARM (OPE-989) — the nearest honest equivalent to the ✋ reaction.
+//
+// ════════════════════════════════════════════════════════════════════════════════════════════════
+// 🔴 NOTION SENDS NO REACTION WEBHOOK. THIS IS THE VENDOR EVIDENCE, AND IT IS WHY THIS FILE READS A
+//    COMMENT INSTEAD OF AN EMOJI.
+// ════════════════════════════════════════════════════════════════════════════════════════════════
+//
+// Notion's complete webhook event catalogue (developers.notion.com/reference/webhooks-events-
+// delivery, read 2026-08-23) is `page.*`, `database.*`/`data_source.*` and exactly THREE comment
+// events: `comment.created`, `comment.updated`, `comment.deleted`. There is no reaction resource on
+// any of them — the same gap GitHub's webhook catalogue has, and the same answer applies: the
+// trigger is a bare `stop` comment, read at the ingress before anything is dispatched.
+// `channels/turn-cancel.ts`'s `isStopDirective` owns the grammar (one word, optional `/oe ` prefix,
+// optional trailing punctuation) and its header carries the reasoning for why the match is narrow.
+//
+// UNLIKE GITHUB, THE WEBHOOK CARRIES NO TEXT. A Notion `comment.created` delivery is a SIGNAL ONLY
+// (the comment id, not its body — notion-webhook.ts's header), so the two-step fetch
+// (`retrieveComment`) that the webhook core already runs for the ambient path is what supplies the
+// text this arm reads. There is no separate "parse the raw delivery" function here the way GitHub's
+// `parseGitHubStopComment` has one: `notionCommentIsStopDirective` takes the ALREADY-FETCHED comment.
+//
+// THE ACTOR GUARD FAILS CLOSED, THE SAME WAY THE AMBIENT LOOP GUARD DOES (notion-supervisor.ts
+// `classifyNotionComment`). The agent's own reply rides the same webhook (`createCommentReply` fires
+// a fresh `comment.created`), so behind `cancel()` a fail-OPEN identity check is a self-cancel:
+//   1. UNRESOLVED PRIMARY bot user id ⇒ refuse. Without our own id we cannot rule out that this IS
+//      our own comment, so treating it as a stop would be a coin flip on self-cancellation.
+//   2. SELF-authored (`created_by.id` in {@link NotionOwnBotIds.all}) ⇒ refuse. The set is EVERY
+//      configured integration's bot user id (OPE-1921), so a sibling integration's own comment
+//      cannot cancel this one's turn.
+//   3. UNIDENTIFIABLE author (no `created_by.id`) ⇒ refuse (OPE-1906). Arm 2 is the only one that
+//      recognises our own words, and with no id it cannot run — what is left is arm 4, on a field
+//      Notion OMITS. So an author nobody can name could cancel the page's running turn.
+//   4. BOT/integration-authored (`created_by.type` present and not `"person"`) ⇒ refuse — the
+//      bot-to-bot loop guard. 🔴 A BACKSTOP, never the self-check: `created_by.type` is usually
+//      ABSENT on a comment, so a FOREIGN bot reads here as a person. Arm 2's set is what answers
+//      "is it ours"; arm 5 is what answers "we cannot tell".
+//   5. INCOMPLETE OWN-ID SET on an author Notion states nothing about ⇒ refuse (OPE-1921). One
+//      configured integration's id did not resolve, so arm 2 could not have recognised that
+//      integration's own `stop`. `classifyNotionComment` step 5 fails closed on the same fact.
+// Any of these five leaves the comment UNCLASSIFIED as a stop, not rejected outright: the webhook
+// core falls through to its ordinary ambient/classify path, where the very same checks drop it again
+// for the ordinary reason.
+// 🔴 A GENUINE HUMAN `stop` PASSES ALL FIVE ONLY WHILE THIS DEPLOYMENT CAN NAME ITS OWN IDS, and the
+// two identity arms are the exceptions. Arm 1 (primary unresolved) and arm 5 (a sibling unresolved,
+// on an author Notion states nothing about) refuse a REAL person's `stop` too: the comment then takes
+// the ordinary classify path, which drops it for its own fail-closed reason, so no `cancelAnchoredTurn`
+// runs and the person gets no reply. That is the accepted cost of never self-cancelling on a coin
+// flip — an identity we cannot establish is not treated as a human — and it is why the drop is
+// recorded under the classifier's reason rather than as a cancel.
+//
+// THE CONVERSATION KEY IS THE PAGE, NOT THE DISCUSSION. The Notion doc-session is PAGE-scoped
+// (notion-supervisor.ts: "a page-scoped standing session aware of all the doc's discussions"), so a
+// stop trigger anywhere on the page names the newest running turn on that page — the `/oe stop`
+// grain the Teams arm's header documents. `notionConversationKey` (notion-identity.ts) is the ONE
+// derivation both {@link bindNotion}'s `anchorChannelId` and this file's `routeNotionStopComment`
+// use, so the registry write and the registry read can never drift into two spellings.
+//
+// IT SUPPRESSES THE REST OF THE PIPELINE FOR ITS OWN DELIVERY. notion-webhook.ts's `deliver()` runs
+// this check BEFORE the ambient gate and BEFORE classify/dispatch — waking the supervisor on the very
+// comment that asked it to stand down would be exactly the failure GitHub's `github.ts` avoids by
+// suppressing its own ambient leg for a stop delivery.
+
+import {
+  cancelAnchoredTurn,
+  resolvePartition,
+  turnChannelKey,
+  type AttachSessionForCancel,
+  type CancelOutcome,
+} from "@open-everywhere/core/agent/adapter-api.js";
+import { isStopDirective } from "@open-everywhere/core/agent/adapter-api.js";
+import { buildNotionAuth, notionConversationKey } from "./notion-identity.js";
+import { richTextToPlainText, type NotionComment } from "./notion-api.js";
+import type { NotionOwnBotIds } from "./notion-bot-user.js";
+
+/**
+ * Is this FETCHED comment a genuine, human-authored stop directive? NEVER THROWS.
+ *
+ * FAIL CLOSED throughout — see this file's header for the five actor-guard arms. An unresolved
+ * PRIMARY id refuses EVERYTHING, not just the self-check: without our own identity there is no
+ * distinguishing "a human said stop" from "we said stop", and the safe answer is to not treat it as
+ * a stop at all (it still reaches the ordinary ambient path, which drops it for its own reasons).
+ */
+export function notionCommentIsStopDirective(comment: NotionComment, own: NotionOwnBotIds): boolean {
+  if (!isStopDirective(richTextToPlainText(comment.rich_text))) return false;
+  if (!own.primary) return false; // can't rule out self — fail closed
+  const author = comment.created_by;
+  // OUR OWN WORDS, from ANY configured integration (OPE-1921) — never only the one that verified
+  // this delivery. A sibling integration's `stop` used to reach `cancelAnchoredTurn`.
+  if (author?.id !== undefined && own.all.has(author.id)) return false;
+  // 🔴 AN AUTHOR WE CANNOT IDENTIFY IS NOT A HUMAN (OPE-1906). The self-check above is the only arm
+  // that recognises our own words, and with no `created_by.id` it cannot run — the line below would
+  // then rest on `created_by.type`, which Notion OMITS on a comment. Without this, an unidentifiable
+  // author could CANCEL the page's running turn while the same author saying anything else is
+  // dropped by `classifyNotionComment` step 3. Same posture, one step apart.
+  if (!author?.id) return false; // unidentified author — fail closed
+  if (author.type && author.type !== "person") return false; // bot/integration-authored
+  // 🔴 A SIBLING WE COULD NOT RESOLVE IS A SELF-CHECK THAT DID NOT RUN (OPE-1921). With one
+  // integration's bot id missing, this author is either a person or that integration, and Notion's
+  // partial `created_by` cannot say which — so a self-cancel is back on the table. Refuse.
+  if (!own.complete && author.type !== "person") return false;
+  return true;
+}
+
+/** The facts a stop delivery carries, ALREADY RESOLVED by the webhook core's own steps (the
+ *  authenticated page, the roster-aware workspace, the delivery's selected integration) — this file
+ *  never re-derives any of them from the payload. */
+export interface NotionStopComment {
+  readonly workspaceId?: string;
+  readonly pageId: string;
+  readonly discussionId?: string;
+  readonly credentialId?: string;
+  /** WHO asked (comment.created_by.id) — recorded on the audit row, never used to decide (the
+   *  actor guard already ran in {@link notionCommentIsStopDirective}). */
+  readonly requesterId?: string;
+}
+
+/** Injected seams, so parse + guard + cancel is unit-tested without a live Notion integration. */
+export interface NotionStopDeps {
+  readonly attachSession: AttachSessionForCancel;
+  /** Injectable for the test; defaults to the shared `cancelAnchoredTurn`. There is no second
+   *  cancel implementation behind this — the seam exists to observe the call, never to replace it. */
+  readonly cancel?: typeof cancelAnchoredTurn;
+}
+
+/** Why the arm did what it did — for the caller's log, never for a person to read. */
+export type NotionStopOutcome =
+  | { readonly stopped: false; readonly reason: string }
+  | { readonly stopped: true; readonly outcome: CancelOutcome };
+
+/**
+ * Cancel the turn running on the page this stop directive was posted into.
+ *
+ * THE CONVERSATION KEY ONLY. A comment or discussion id is not the turn's anchor message — the
+ * anchor is the human's triggering message, which the registry keys on the PAGE (see this file's
+ * header) — so offering an `anchorKey` here would be a lookup that always misses.
+ */
+export async function routeNotionStopComment(stop: NotionStopComment, deps: NotionStopDeps): Promise<NotionStopOutcome> {
+  const conversationKey = notionConversationKey(stop.workspaceId, stop.pageId);
+  const channelKey = conversationKey ? turnChannelKey("notion", conversationKey) : undefined;
+  if (!channelKey) return { stopped: false, reason: "stop: no conversation key" };
+  const partition = resolvePartition({
+    channel: { kind: "notion" },
+    session: {
+      auth: {
+        current: buildNotionAuth({
+          workspaceId: stop.workspaceId,
+          pageId: stop.pageId,
+          ...(stop.discussionId ? { discussionId: stop.discussionId } : {}),
+          ...(stop.credentialId ? { credentialId: stop.credentialId } : {}),
+          ...(stop.requesterId ? { principalId: stop.requesterId } : {}),
+        }),
+      },
+    },
+  });
+  const result = await (deps.cancel ?? cancelAnchoredTurn)({
+    org: partition.org,
+    platform: "notion",
+    workspace: partition.workspace,
+    ...(stop.requesterId ? { requestedBy: stop.requesterId } : {}),
+    // `reaction` names the AFFORDANCE class, not the vendor mechanism: a member pressed the stop
+    // control this surface offers. `command` is the slash-command door and `tool` is the agent's
+    // own verb — neither is what happened here. The audit row's job is "which door do people reach
+    // for", and a Notion stop comment is the same door as a Slack ✋.
+    via: "reaction",
+    query: { channelKey },
+    attachSession: deps.attachSession,
+  });
+  return { stopped: true, outcome: result.outcome };
+}