@open-everywhere/provider-notion 0.1.0

package/agent/tools/read_notion_comments.ts

@@ -0,0 +1,250 @@
+// The comments/inline-discussion read tool for the ambient Notion surface — the SIBLING of
+// read_notion_page (which returns the page BODY). The comment thread you were WOKEN on is already in
+// context; this pulls the OTHER discussions on the page (a second commenter on another block, an
+// older resolved argument the reply needs to reconcile) BY REFERENCE — fetched on demand, never
+// inlined into the wake, so a heavily-annotated page can't blow the backscroll budget.
+//
+// SURFACE GATE + REPLAY DOCTRINE + UNTRUSTED WRAP: identical to read_notion_page.ts — a per-session
+// dynamic resolver gated on `notion ∈ sources` (workerChatArmMount) with a per-turn origin fence
+// (assertTurnSurface), a top-level factored defineTool (never an inline literal — the bundler's
+// build-time transform hoists one under a build-order-counter name that shifts across deploys; eve
+// derives a session-scoped step id for a factored, unstamped entry and self-heals it on cold resume,
+// OPE-867), and NO `approval:` (read-only).
+//
+// DOMAIN FENCE (channels/notion-scope.ts, OPE-236): BOTH caller-supplied ids are gated — `page`, and
+// `block`, which addresses a block directly and never touches `page` at all. Fail closed on either,
+// and audit the refusal; the one deployment-wide credential fences the workspace, never the domain.
+//
+// Comment bodies are EXTERNAL, UNTRUSTED content (commenters include workspace guests / externals),
+// so the whole rendered listing is wrapped through ingestUntrusted (toModelOutput) — the model must
+// treat comment text as DATA, not instructions. Author ids are surfaced as DATA too, never as a
+// trust signal.
+//
+// 🔴 THIS TOOL IS THE DELEGATED WORKER'S ONLY (OPE-1014). It has ONE mount arm — the chat arm — and
+// that arm now mounts on the `task` grain alone (access/source-scoped-mount.ts `workerChatArmMount`).
+// A conversational Notion seat reads the same comment layer through `read_channel` (channels/
+// notion-read.ts), which sweeps every discussion on the page headed by its anchor block, a SUPERSET
+// of what this tool returns, and `read_thread`, which reads the one discussion the turn is in. Since
+// OPE-1039 the generic pair carries the OPE-1026 dated-read framing too — the `readAt` stamp, the
+// per-line age and the HISTORY marker that stops the model reading a stale comment's claim as the
+// page's present state — so the seat loses no safety framing by taking the generic route.
+//
+// The worker kept it because it had no substitute: access/worker-seat.ts withholds `read_channel` /
+// `read_thread` from every delegated worker. That is no longer the whole story (OPE-1064): `WORK_ROLES`
+// now gives Notion a CONTAINER row too, so a work-granted domain's delegated worker also holds the
+// generic `read_work_channel` / `read_work_thread` pair, which the paragraph above already says
+// SUPERSEDES this tool's own read (a superset via `read_channel`'s discussion sweep). This tool has
+// no work arm of its own to fall back on, so the `task` grain is still its whole mount — it stays
+// live for now because retiring a shipped tool is its own reviewed change (filed on OPE-1064), not
+// a side effect of adding the neutral path beside it.
+
+import { defineDynamic, defineTool } from "eve/tools";
+import { z } from "zod";
+import { readNotionComments, resolveBlockOwningPage, resolveNotionCredential, type NotionCommentSummary } from "../channels/notion-api.js";
+import { notionCallerCredential } from "../channels/notion-credentials.js";
+import { assertNotionActingIdentity } from "../channels/notion-acting-identity.js";
+import { assertNotionBlockAllowed, assertNotionPageAllowed } from "../channels/notion-scope.js";
+import {
+  ingestUntrustedModelOutput,
+  assertTurnSurface,
+  TurnOriginFenceError,
+  auditOriginFenceRefusal,
+  bindFrom,
+  workerChatArmMount,
+  getConfig,
+  preRegisterDynamicEntry,
+  resolvePartition,
+  declaredWorkspaceTrust,
+  ageAtRead,
+  type SurfaceTrust,
+  type BindableContext,
+} from "@open-everywhere/core/agent/adapter-api.js";
+
+const MAX_COMMENTS = 100;
+const MAX_BLOCK_SCANS = 80;
+
+/** Render the flattened comments into a human-readable, per-discussion listing. The WHOLE string is
+ *  wrapped untrusted by toModelOutput, so bodies + author ids inside it are DATA.
+ *
+ *  OPE-1026 — each line carries its age at the moment of the read (see {@link ageAtRead}), the same
+ *  fact `read_linear_issue.ts` renders for Linear comments: the discriminator between "an old comment
+ *  said X" and "X is true now". `readAt` is optional so a stored output from before this field
+ *  existed still renders — with no invented age. */
+function renderComments(comments: readonly NotionCommentSummary[], readAt?: string): string {
+  if (comments.length === 0) return "";
+  // Group by anchor (block/page) → each anchor is a distinct inline discussion.
+  const byAnchor = new Map<string, NotionCommentSummary[]>();
+  for (const c of comments) {
+    const key = c.anchorId ?? "(unknown)";
+    let list = byAnchor.get(key);
+    if (!list) {
+      list = [];
+      byAnchor.set(key, list);
+    }
+    list.push(c);
+  }
+  const sections: string[] = [];
+  for (const [anchor, list] of byAnchor) {
+    const disc = list.find((c) => c.discussionId)?.discussionId;
+    const head = `discussion on block ${anchor}${disc ? ` (discussion_id ${disc})` : ""}:`;
+    const lines = list.map((c) => {
+      const who = c.authorId ? `${c.authorKind ?? "user"} ${c.authorId}` : "unknown author";
+      const when = c.createdTime ? ` at ${c.createdTime}` : "";
+      const age = ageAtRead(c.createdTime, readAt);
+      const old = age ? ` (${age} before this read)` : "";
+      return `  - ${who}${when}${old}: ${c.text}`;
+    });
+    sections.push([head, ...lines].join("\n"));
+  }
+  return sections.join("\n\n");
+}
+
+// FACTORED + PRE-REGISTERED (see read_notion_page.ts / access/window-gated.ts REPLAY DOCTRINE).
+// Exported for the unit test (its toModelOutput = the untrusted-wrap assertion).
+export const readNotionCommentsEntry = defineTool({
+  description:
+    "Read the comments / inline discussions on a Notion page (this doc, or another page shared with " +
+    "the integration). Use it when a reply needs OTHER discussions on the page — a comment on a " +
+    "different block, or an older thread — beyond the one you were woken on (already in context). " +
+    "Pass `block` to read just one block's inline discussion. Bounded; truncates a heavily-commented page.",
+  inputSchema: z.object({
+    page: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("The Notion page id whose comments to read. Defaults to THIS doc — the page the comment you're on lives in."),
+    block: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("Read ONLY this block's inline discussion (a block/page id), instead of sweeping the whole page."),
+  }),
+  outputSchema: z.object({
+    page: z.string(),
+    discussions: z.number(),
+    comments: z.number(),
+    blocksScanned: z.number(),
+    truncated: z.boolean(),
+    text: z.string(),
+    // OPE-1026 — the moment the comments below were fetched, stamped by `execute` and carried to
+    // `toModelOutput`. Optional because `toModelOutput` also runs over outputs stored before this
+    // field existed; the render drops the read-time line rather than inventing one (see
+    // read_linear_issue.ts's `readAt`, the pattern this copies).
+    readAt: z.string().optional(),
+    // OPE-331 — the bound workspace's declared tier, carried execute → toModelOutput. Same shape and
+    // same reasoning as read_notion_page's field; model-invisible behind the authored projection.
+    workspaceTrust: z.enum(["internal", "public"]).optional(),
+  }),
+  // NO `approval:` — read-only; a dynamic-tool approval fn fails a resumed session's replay lookup
+  // (same pin read_notion_page / access/window-gated.ts document). Absent approval === never() is correct.
+  async execute(input, ctx2) {
+    // Per-turn surface fence (finding 1b): a non-Notion-origin turn on a unified window must not read
+    // Notion comments even though the tool is armed for the session.
+    // OPE-732: the fence's refusal is audited here (see read_notion_page.ts's note).
+    try {
+      assertTurnSurface(ctx2 as BindableContext, "notion");
+    } catch (err) {
+      if (err instanceof TurnOriginFenceError) await auditOriginFenceRefusal(ctx2 as BindableContext, "notion");
+      throw err;
+    }
+    // Default to THIS session's page (bindFrom(ctx).surface = the page id for Notion).
+    const page = input.page ?? bindFrom(ctx2 as BindableContext).surface;
+    if (!page) throw new Error("No Notion page id available for this session — pass `page` explicitly.");
+    // DOMAIN FENCE (OPE-236) — see read_notion_page.ts and channels/notion-scope.ts. The one
+    // deployment-wide integration key bounds the WORKSPACE, not the domain, so the domain allowlist
+    // is ours to enforce: fail closed on an unresolvable page, audit every refusal.
+    const domains = getConfig().loadDomains();
+    await assertNotionPageAllowed(ctx2 as BindableContext, page, domains);
+    // OPE-467 / OPE-499 — the carried delivery credential decides, when one is present; the CALLING
+    // domain's own binding is the fallback (see read_notion_page.ts / notion-credentials.ts).
+    // OPE-505: `cred` is the key AND its endpoint rules; spreading it carries the fence into every
+    // REST call below (notion-api.ts funnels them all through one guarded fetch).
+    // 🔴 OPE-1525 — THE OWN-ACCOUNT GATE, on the line below's behalf. `notionCallerCredential`
+    // resolves an `install`-family key, so a member who asked to act with THEIR OWN Notion account
+    // has no answer here. This tool is the DELEGATED WORKER's own arm — the grain the live
+    // substitution ran in — so leaving it ungated while `read_notion_page` is gated would move the
+    // defect one verb along. The gate refuses that turn and writes the `connector.acting_identity`
+    // row either way; see channels/notion-acting-identity.ts.
+    await assertNotionActingIdentity(ctx2 as BindableContext, "read_notion_comments");
+    const cred = await resolveNotionCredential(notionCallerCredential(ctx2 as BindableContext, domains));
+    if (!cred) throw new Error("no value stored under db:notion:channel-key — cannot read the comments.");
+    // `block` NEEDS ITS OWN GATE: the drill-in addresses the block directly and never touches `page`
+    // (notion-api.ts readNotionComments returns early on it), so fencing `page` alone would leave the
+    // whole fence bypassable in one argument. Costs one `GET /v1/blocks/{id}` only when the block
+    // isn't already in scope by id — the common case (a top-level block of this very page) still
+    // pays it, which is the honest price of not trusting a caller-supplied id.
+    if (input.block) {
+      await assertNotionBlockAllowed(ctx2 as BindableContext, input.block, domains, (id) => resolveBlockOwningPage(id, { ...cred }));
+    }
+    const res = await readNotionComments(page, {
+      ...cred,
+      block: input.block,
+      maxComments: MAX_COMMENTS,
+      maxBlockScans: MAX_BLOCK_SCANS,
+    });
+    // OPE-1026 — the moment the fetch above returned. Stamped AFTER the fetch, so it never claims a
+    // read is fresher than it is (see read_linear_issue.ts's `readAt`).
+    const readAt = new Date().toISOString();
+    // OPE-331 — resolve the workspace tier where a ctx exists; fail-soft to absent (the table's
+    // pre-existing fail-closed answer).
+    let workspaceTrust: SurfaceTrust | undefined;
+    try {
+      workspaceTrust = declaredWorkspaceTrust(resolvePartition(ctx2 as BindableContext).workspaceKey);
+    } catch {
+      workspaceTrust = undefined;
+    }
+    return {
+      page,
+      discussions: res.discussionCount,
+      comments: res.comments.length,
+      blocksScanned: res.blocksScanned,
+      truncated: res.truncated,
+      text: renderComments(res.comments, readAt),
+      readAt,
+      ...(workspaceTrust !== undefined ? { workspaceTrust } : {}),
+    };
+  },
+  toModelOutput(output) {
+    const header =
+      output.comments === 0
+        ? `Notion page ${output.page} has no readable comments.`
+        : `Notion page ${output.page} — ${output.comments} comment(s) across ${output.discussions} discussion(s):`;
+    const suffix = output.truncated ? "\n\n[truncated — the page has more comments/blocks than shown]" : "";
+    // OPE-1026 — THE PROVENANCE LINE, only when there is comment text to date (Linear's pattern,
+    // §OPE-1012): the comments above are dated against THIS read, and a comment's claim about status
+    // or approval is HISTORY, not the page's current state. `read_notion_page` is the tool that reads
+    // the page's current content — this one never claims to.
+    const asOf =
+      output.comments > 0 && output.readAt
+        ? `\n\nRead live at ${output.readAt}: the comments above are HISTORY, each dated against this read. A comment's claim about status, approval or progress is not the page's current state — read the page itself (read_notion_page) for that.`
+        : "";
+    const body = output.comments === 0 ? header : `${header}\n${output.text}${suffix}${asOf}`;
+    // OPE-324 — `workspaceTrust` (plumbed OPE-331) is the DECISION here, same route and same meaning
+    // as read_notion_page's (see its note): a vouched-internal workspace fences without tainting, an
+    // unvouched one falls closed and taints, and the `assumed` flag says the operator never vouched
+    // it rather than that OE could not look.
+    return ingestUntrustedModelOutput(body, {
+      source: `notion comments ${output.page}`,
+      ingestion: {
+        kind: "notion",
+        label: "read_notion_comments",
+        ...(output.workspaceTrust !== undefined ? { workspaceTrust: output.workspaceTrust } : {}),
+      },
+    });
+  },
+});
+preRegisterDynamicEntry("read_notion_comments", "_single", readNotionCommentsEntry);
+
+export default defineDynamic({
+  events: {
+    // session.started ONLY: a session runs on exactly one surface (see read_notion_page.ts).
+    "session.started": (_event, ctx) => {
+      // THE CHAT ARM (§A5), narrowed to the DELEGATED-WORKER grain by OPE-1014: mount iff `notion ∈`
+      // this window's sources AND the grain is `task`. This tool has NO work arm, so `task` is its whole
+      // mount: a conversational Notion seat reads the same comment layer through the generic
+      // `read_channel` / `read_thread`, which sweep a superset of what this tool returns.
+      if (!workerChatArmMount(ctx as BindableContext, "notion", () => getConfig().loadDomains())) return null;
+      return readNotionCommentsEntry;
+    },
+  },
+});

package/agent/tools/read_notion_page.ts

@@ -0,0 +1,351 @@
+// The doc-body read tool for the ambient Notion surface (notion-ambient-surface-design.md
+// Step 0). The ambient supervisor judges + replies off the COMMENT context (a comment usually
+// anchors to specific text); when a reply needs the doc's own prose — to answer a question about
+// the page, or to catch a factual problem in it — the agent pulls the body with this tool. Body
+// BY REFERENCE (chat-vs-ticketing-and-tool-uniformity.md rec #3): the doc is fetched on demand,
+// NEVER inlined into the wake, so a big page can't blow the backscroll budget.
+//
+// SURFACE GATE: this reads a *Notion* page, so it only makes sense on a Notion session. Authored
+// as a per-session DYNAMIC resolver (defineDynamic) that returns the real tool only when the
+// session platform is `notion`, and `null` (the tool is absent, not merely throwing) elsewhere —
+// the exact discipline access/source-scoped-mount.ts states, so a Slack/Discord agent never sees it.
+//
+// TWO PLANES SINCE OPE-913, and they differ in mount, fence and CREDENTIAL:
+//   • CHAT plane — a Notion-origin turn reads its own wake container's page on the chat credential
+//     (`channel-key`). Narrowed to the DELEGATED-WORKER grain by OPE-1014 — see the note below.
+//   • WORK plane — any session whose DOMAIN declares a Notion work credential reads that domain's
+//     pages, from any surface, on the WORK credential. This is what makes a Slack-woken delegated
+//     worker able to ground itself in the spec it was told to build from (the OPE-913 soak
+//     finding). A domain that declares no work credential holds no grant and sees no change.
+// channels/notion-work.ts owns the grant decision; both planes fence the target page to the
+// caller's own domain, and neither can read a page the domain does not own.
+//
+// 🔴 THE CHAT ARM IS THE DELEGATED WORKER'S (OPE-1014), AND THE OPE-988 RULING IS WHY IT IS SAFE TO
+// NARROW. Tommy's ruling in channels/notion-read.ts states that PAGE CONTENT STAYS OUT OF THE CHAT
+// PLANE, and it names the seat's own route in the same breath: "a seat that needs the document
+// itself uses the GRANT-MOUNTED `read_notion_page` or delegates to a worker". Both of those survive
+// this change untouched — the WORK arm above is grain-blind, and a worker holds the chat arm. What
+// goes is the third route the ruling never named: an UNGRANTED conversational Notion seat reading
+// page prose off the chat credential. That seat now delegates, exactly as the ruling says.
+//
+// The worker keeps the arm for now, though it is no longer the ONLY route (OPE-1064): `WORK_ROLES`
+// gives Notion a CONTAINER row too (the same "team-key" role its entity row already names), so a
+// work-granted domain's delegated worker also holds the generic `read_work_channel` /
+// `read_work_thread` pair — access/worker-seat.ts still withholds `read_channel` / `read_thread`
+// from it, but the neutral pair now covers what only this vendor arm covered before. The two are
+// NOT identical: this tool returns the whole page (title + body) in one read, the generic pair
+// splits root/thread the Slack way. Retiring this arm in favour of the generic pair entirely is a
+// follow-up (filed on OPE-1064), not this change — it changes a shipped tool's shape and deserves
+// its own review.
+//
+// DOMAIN FENCE: the `page` argument is a caller-supplied id, and the one deployment-wide Notion
+// credential cannot tell one domain's pages from another's — so which pages this session may read is
+// OURS to decide, in channels/notion-scope.ts (OPE-236). Fail closed, and every refusal is audited.
+//
+// Output is wrapped untrusted (toModelOutput → ingestUntrusted): a page body is written by
+// arbitrary workspace members, so the model must treat it as DATA, not instructions.
+
+import { defineDynamic, defineTool } from "eve/tools";
+import { z } from "zod";
+import { readNotionPage, readNotionPageIdentity, resolveBlockOwningPage, resolveNotionCredential } from "../channels/notion-api.js";
+import { notionCallerCredential } from "../channels/notion-credentials.js";
+import { assertNotionActingIdentity } from "../channels/notion-acting-identity.js";
+import { assertNotionPageAllowed, assertNotionPageAllowedOrResolveBlock, assertNotionWorkPageAllowed } from "../channels/notion-scope.js";
+import { notionWorkGrant, notionWorkMount, notionWorkspacesOf, type NotionWorkGrant } from "../channels/notion-work.js";
+import {
+  ingestUntrustedModelOutput,
+  assertTurnSurface,
+  TurnOriginFenceError,
+  auditOriginFenceRefusal,
+  bindFrom,
+  workerChatArmMount,
+  getConfig,
+  preRegisterDynamicEntry,
+  resolvePartition,
+  declaredWorkspaceTrust,
+  noteAuthoredRecordRead,
+  type SurfaceTrust,
+  type BindableContext,
+} from "@open-everywhere/core/agent/adapter-api.js";
+
+const MAX_CHARS = 20_000;
+const MAX_BLOCKS = 200;
+
+// FACTORED (see access/window-gated.ts's REPLAY DOCTRINE): a top-level defineTool const, never an
+// inline literal in the handler — eve's bundler transform hoists an inline one under a
+// build-order-counter name that shifts across deploys. eve derives a session-scoped step id for a
+// factored, unstamped entry and self-heals it on cold resume (OPE-867). Exported for the read-scope
+// test, which drives execute() to prove the DOMAIN FENCE is actually
+// WIRED here — a fence the tool forgets to call is worth nothing, and the module test alone would
+// not notice its removal.
+export const readNotionPageEntry = defineTool({
+        description:
+          "Read the text of a Notion page (this doc, or another page shared with the integration). " +
+          "Use it when a reply needs the doc's own content — to answer a question about the page or " +
+          "catch a problem in it. Returns the page's top-level text (truncated if very long); the " +
+          "comment thread you were woken on is already in your context. It reads under the shared " +
+          "team integration, never under the asker's own Notion account, so it sees what the team " +
+          "integration was shared and not what they can see.",
+        inputSchema: z.object({
+          page: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("The Notion page id to read (e.g. a UUID). Defaults to THIS doc — the page the comment you're on lives in."),
+        }),
+        outputSchema: z.object({
+          page: z.string(),
+          // OPE-1714 — the page's own title and Notion url, from a separate GET on the page object
+          // (the body read returns blocks alone). The model gets a name and a link it can hand a
+          // human instead of a bare uuid. Optional both ways: a stored output from before these
+          // fields existed still renders, and the identity fetch is fail-soft, so a page whose
+          // object could not be read renders exactly as it did before. UNTRUSTED — a workspace
+          // member chooses the title, and toModelOutput wraps the whole render accordingly.
+          title: z.string().optional(),
+          url: z.string().optional(),
+          blocks: z.number(),
+          truncated: z.boolean(),
+          text: z.string(),
+          // OPE-1026 — the moment the fetch below returned, stamped by execute and carried to
+          // toModelOutput. Optional for the same reason `read_linear_issue.ts`'s `readAt` is: a
+          // stored output from before this field existed still renders, with no invented read time.
+          readAt: z.string().optional(),
+          // OPE-331 — the BOUND WORKSPACE's declared tier, carried from execute (which has a ctx) to
+          // toModelOutput (which does not). It is the input the source-tier table's `notion` row needs, and
+          // the reason every row this seam produced read `assumed`. Model-INVISIBLE: an authored
+          // toModelOutput means the projection is what the model sees, never this object. Absent when
+          // the operator has not vouched the workspace — see declaredWorkspaceTrust for why silence
+          // stays absent rather than becoming `"public"`.
+          workspaceTrust: z.enum(["internal", "public"]).optional(),
+        }),
+        // NO `approval:` — a dynamic-tool approval fn only registers at session.started resolve
+        // time, so a resumed session's replay lookup fails and eve kills the turn (the same pin
+        // access/window-gated.ts documents). Read-only, so absent approval === never() is correct.
+        async execute(input, ctx2) {
+          const domains = getConfig().loadDomains();
+          // Per-turn surface fence (finding 1b): on a unified session a non-Notion-origin turn
+          // must not read Notion pages on the CHAT plane, even though the tool is armed for the
+          // session. OPE-732: the fence's refusal is audited here — assertTurnSurface itself stays
+          // a pure, synchronous, store-free check (see identity/binding.ts).
+          //
+          // OPE-913 — THE WORK PLANE IS THE ONE WAY PAST IT. A non-Notion-origin turn is admitted
+          // only when the caller's DOMAIN holds the Notion work grant (channels/notion-work.ts).
+          // That is not a hole in the fence: the grant is a reviewed config declaration naming the
+          // credential the read runs under, and the target page is still fenced to the caller's own
+          // domain below (assertNotionWorkPageAllowed). With no grant the refusal is byte-identical
+          // to before — same audit row, same thrown error.
+          let workGrant: NotionWorkGrant | undefined;
+          try {
+            assertTurnSurface(ctx2 as BindableContext, "notion");
+          } catch (err) {
+            if (!(err instanceof TurnOriginFenceError)) throw err;
+            workGrant = notionWorkGrant(ctx2 as BindableContext, domains);
+            if (!workGrant) {
+              await auditOriginFenceRefusal(ctx2 as BindableContext, "notion");
+              throw err;
+            }
+          }
+          // Default to THIS session's page (bindFrom(ctx).surface = the page id for Notion — see
+          // identity/binding.ts bindNotion). On the WORK plane there is no such default to take:
+          // the caller's surface is a Slack channel / a repo / a Linear team, and `bindFrom().surface`
+          // would hand a non-Notion id to the Notion API. Require the argument instead of guessing.
+          const requestedPage = input.page ?? (workGrant ? undefined : bindFrom(ctx2 as BindableContext).surface);
+          if (!requestedPage) {
+            throw new Error(
+              workGrant
+                ? "Pass `page` explicitly — this session was not woken on a Notion page, so there is no page to default to."
+                : "No Notion page id available for this session — pass `page` explicitly.",
+            );
+          }
+          // Credential resolved BEFORE the fence (OPE-352): resolving a block/discussion id to its
+          // owning page needs a working Notion API call, so the resolver has to be built first. This
+          // does NOT reintroduce a network dependency into a plain refusal — when there is no key, the
+          // resolver below is a no-op stub (never calls fetch), so an out-of-scope id still refuses
+          // with zero network and zero key, exactly as before (pinned in notion-read-scope-test.ts §6).
+          // OPE-467 / OPE-499 — a delivery-woken session reads under the credential that VERIFIED
+          // the delivery (carried on the auth attributes); an agent-initiated session (no delivery)
+          // falls back to the CALLING domain's own binding, or the org default when it binds none.
+          // Resolved off the caller's OWN surface/context, known before the fence runs (the
+          // block-resolution walk below needs a working key to run at all). That is not a weaker
+          // check: notion-scope.ts only ever admits the caller's own page or a page in the caller's
+          // own domain, so caller and target resolve to the same domain by construction.
+          // OPE-505: the key AND its endpoint rules, resolved together and spread together, so the
+          // credential's fence reaches every REST call below.
+          //
+          // OPE-913 — THE WORK PLANE RUNS ON A DIFFERENT CREDENTIAL, and that is the point of the
+          // split. `notionCallerCredential` resolves the CHAT key (`channel-key`, the comment
+          // surface's plumbing). A work-granted read runs on the credential the DOMAIN declared for
+          // its work role, so an organisation can share its chat integration with the comment pages
+          // only and its work integration with the page trees the agent may build from.
+          //
+          // 🔴 ONE VARIABLE FEEDS BOTH THE RESOLVE AND THE FAILURE MESSAGE, deliberately. Naming the
+          // credential in a literal string that a second expression resolves is how a test comes to
+          // assert a plane it is not actually exercising: the message says "work credential" while
+          // the call resolves the chat one, and nothing notices. Interpolating `credentialId` makes
+          // the message an OBSERVABLE of the resolution instead of a claim about it.
+          //
+          // 🔴 OPE-1525 — THE OWN-ACCOUNT GATE RUNS FIRST, ON THE LINE BELOW'S BEHALF. Both arms of
+          // the choice below resolve a TEAM key, so a member who asked to act with THEIR OWN Notion
+          // account has no answer here — and answering anyway is the defect the ticket traced. The
+          // gate refuses that turn (naming the consent route, or the granted tool, or saying plainly
+          // that neither exists) and writes the `connector.acting_identity` row either way.
+          await assertNotionActingIdentity(ctx2 as BindableContext, "read_notion_page");
+          const credentialId = workGrant ? workGrant.credential : notionCallerCredential(ctx2 as BindableContext, domains);
+          const cred = await resolveNotionCredential(credentialId);
+          // DOMAIN FENCE (OPE-236 + OPE-352). Notion's own enforcement bounds the WORKSPACE — one
+          // deployment-wide integration key, identical for every domain — so it cannot tell domain A's
+          // pages from domain B's. channels/notion-scope.ts is the allowlist on top: own page always,
+          // otherwise caller and target must land in the SAME domain (roster, then a container entry
+          // claim), and an unresolvable page is REFUSED, never defaulted readable. The refusal is
+          // audited there — the gap this closes was silent.
+          //
+          // OPE-352: the Notion worker intermittently hands this tool a DISCUSSION BLOCK id instead of
+          // the page it lives on, and a block id fails the plain page fence every time (it is never
+          // itself rostered/claimed) — a silent-looking `target-unassigned` refusal even when the
+          // block's owning page was perfectly in scope. With a working credential, fall back to
+          // resolving `requestedPage` as a block id to its parent page (bounded walk, see
+          // resolveBlockOwningPage) and fence THAT page through the exact same decision — never a
+          // separate, looser check. `page` below is the id actually authorized (the original id, or
+          // the resolved parent page when only resolution admitted it) — the content fetch and the
+          // reported `page` field both use it, never the raw `requestedPage`.
+          //
+          // OPE-913 — THE WORK PLANE TAKES THE PLAIN FENCE, deliberately. `notionReadScope` reads the
+          // caller's domain out of its own Notion surface key, which a Slack-woken caller does not
+          // have, so the work plane fences through `notionWorkScope` instead: the caller's domain
+          // comes from whatever surface woke it, and the target must still land in THAT domain. No
+          // block-parent resolution hop here — the OPE-352 hop exists because the Notion COMMENT
+          // worker is handed discussion-block ids by its own wake, which a cross-surface caller never
+          // is. A block id from the work plane refuses, and the refusal says how to pass a page id.
+          let page: string;
+          if (workGrant) {
+            await assertNotionWorkPageAllowed(
+              ctx2 as BindableContext,
+              requestedPage,
+              workGrant.domain,
+              domains,
+              notionWorkspacesOf(workGrant.domain),
+            );
+            page = requestedPage;
+          } else if (cred) {
+            page = await assertNotionPageAllowedOrResolveBlock(ctx2 as BindableContext, requestedPage, domains, (id) => resolveBlockOwningPage(id, { ...cred }));
+          } else {
+            await assertNotionPageAllowed(ctx2 as BindableContext, requestedPage, domains);
+            page = requestedPage;
+          }
+          if (!cred) {
+            throw new Error(
+              workGrant
+                ? `no value stored for this domain's Notion work credential "${credentialId}" — cannot read the page.`
+                : "no value stored under db:notion:channel-key — cannot read the page.",
+            );
+          }
+          const res = await readNotionPage(page, { ...cred, maxChars: MAX_CHARS, maxBlocks: MAX_BLOCKS });
+          // OPE-1026 — the moment the fetch above returned. Stamped AFTER the fetch, so it never
+          // claims a read is fresher than it is (see read_linear_issue.ts's `readAt`).
+          const readAt = new Date().toISOString();
+          // OPE-331 — resolve the workspace tier HERE, where a ctx exists, and carry it on the
+          // output. Read-only and fail-soft: an unresolvable partition leaves it absent, which is the
+          // fail-closed answer the table already had.
+          //
+          // 🔴 OPE-913 — THE WORK PLANE LEAVES IT ABSENT, AND THAT IS THE WHOLE POINT. This resolves
+          // the tier of the CALLER'S OWN partition, which on the chat plane IS the Notion workspace
+          // the page lives in. On the work plane the caller is a Slack channel, a repo, a Linear
+          // team — so the same line would hand this Notion page the tier the operator vouched for
+          // SLACK, and a vouched Slack workspace would silently un-taint a page read from an
+          // unvouched Notion workspace. Absent means the read TAINTS (see toModelOutput below), which
+          // is the correct answer for a tier we genuinely cannot resolve here.
+          let workspaceTrust: SurfaceTrust | undefined;
+          if (!workGrant) {
+            try {
+              workspaceTrust = declaredWorkspaceTrust(resolvePartition(ctx2 as BindableContext).workspaceKey);
+            } catch {
+              workspaceTrust = undefined;
+            }
+          }
+          // OPE-1714 — the page's own title and url, on the SAME credential and the SAME fenced page
+          // id the body read used. Separate call because the block-children endpoint carries neither;
+          // fail-soft inside the helper, so a page whose object cannot be read still returns its body.
+          const identity = await readNotionPageIdentity(page, { ...cred });
+          // OPE-1714 — THE REPLY FOOTER'S RECORD HALF, recorded HERE because here is where the host
+          // knows what it fetched. The door writes one reply-provenance entry (`notion`,
+          // `read_notion_page`) and decides on its own, from this turn's `page_id` stamp, whether the
+          // room already holds this page's id — a page the room never named is recorded WITHOUT its
+          // id, so it can never be footed. The title is turn-local and never stored. Never throws.
+          noteAuthoredRecordRead(ctx2 as BindableContext, {
+            kind: "notion-page",
+            id: page,
+            // The id the CALLER asked for as well as the one the fence authorized: OPE-352's hop
+            // resolves a discussion-block id to its owning page, and the room's stamp names the
+            // block. Both name the record this read pulled.
+            alsoKnownAs: [requestedPage],
+            name: identity.title,
+          });
+          return {
+            page,
+            ...(identity.title !== undefined ? { title: identity.title } : {}),
+            ...(identity.url !== undefined ? { url: identity.url } : {}),
+            blocks: res.blockCount,
+            truncated: res.truncated,
+            text: res.text,
+            readAt,
+            ...(workspaceTrust !== undefined ? { workspaceTrust } : {}),
+          };
+        },
+        toModelOutput(output) {
+          // OPE-1714 — name the page and link it where the identity fetch answered. `ref` degrades to
+          // the bare id, which is exactly what every render said before these fields existed.
+          const ref = [output.title, output.url].filter((v) => typeof v === "string" && v.length > 0).join(" — ");
+          const named = ref.length > 0 ? `${output.page} (${ref})` : output.page;
+          const header = output.text.length === 0 ? `Notion page ${named} has no readable text.` : `Notion page ${named}:`;
+          const suffix = output.truncated ? "\n\n[truncated — the page has more content than shown]" : "";
+          // OPE-1026 — THE PROVENANCE LINE (the pattern OPE-1012 shipped for Linear, §asOf). Only
+          // when there is text to date: this is the page's CURRENT content, as of this read — the
+          // counterpart to read_notion_comments, whose comments are HISTORY against the same clock.
+          const asOf =
+            output.text.length > 0 && output.readAt ? `\n\nRead live at ${output.readAt}: the text above is the page's current content, as of that moment.` : "";
+          const body = output.text.length === 0 ? header : `${header}\n${output.text}${suffix}${asOf}`;
+          // 🔴 OPE-324 — `workspaceTrust` (plumbed OPE-331) IS NOW THE DECISION. A page read from a
+          // workspace the operator VOUCHED as internal fences without tainting; an unvouched or
+          // public workspace still taints. Tommy ratified that relaxation on 2026-08-09 — a vouched
+          // internal Notion workspace is org property with org membership, the same trust basis as a
+          // private channel, and the instance-binary rule says so.
+          //
+          // `toModelOutput` has no ctx to resolve config from, so execute resolves the bound
+          // workspace's declared tier and carries it on the output. Absent ⇒ the table falls closed
+          // and the read TAINTS, and the `assumed` flag says why: the operator has never vouched this
+          // workspace (agent/identity/surfaces.ts), not that OE could not look.
+          return ingestUntrustedModelOutput(body, {
+            source: `notion page ${output.page}`,
+            ingestion: {
+              kind: "notion",
+              label: "read_notion_page",
+              ...(output.workspaceTrust !== undefined ? { workspaceTrust: output.workspaceTrust } : {}),
+            },
+          });
+        },
+});
+preRegisterDynamicEntry("read_notion_page", "_single", readNotionPageEntry);
+
+export default defineDynamic({
+  events: {
+    // session.started ONLY: a session runs on exactly one surface, so the platform can't change
+    // mid-session — resolving once is correct and cheaper (see access/source-scoped-mount.ts).
+    "session.started": (_event, ctx) => {
+      // THE CHAT ARM (§A5, see access/source-scoped-mount.ts), narrowed to the DELEGATED-WORKER grain by
+      // OPE-1014: mount iff `notion ∈` this window's sources AND the grain is `task`. The per-turn
+      // origin fence in execute (assertTurnSurface) still stops a non-Notion-origin turn reading a
+      // page on a multi-source window.
+      //
+      // OPE-913 — OR the caller's DOMAIN holds the Notion WORK grant. That is the second, independent
+      // mount path, and it is GRAIN-BLIND: a Slack-woken delegated worker in a work-granted domain
+      // mounts this tool even though `notion ∉ sources` for its window, and so does a granted
+      // conversational seat. Without the grant nothing widens — a domain that declares no Notion work
+      // credential mounts this tool on its delegated workers only.
+      const ok =
+        workerChatArmMount(ctx as BindableContext, "notion", () => getConfig().loadDomains()) ||
+        notionWorkMount(ctx as BindableContext, () => getConfig().loadDomains());
+      if (!ok) return null; // hide unless notion ∈ sources, or the domain holds the work grant
+      return readNotionPageEntry;
+    },
+  },
+});

package/dist/agent/channels/notion-acting-identity.d.ts

@@ -0,0 +1,23 @@
+import { type BindableContext } from "@open-everywhere/core/agent/adapter-api.js";
+/**
+ * Refuse this Notion read when the requester asked to act with their OWN Notion account.
+ *
+ * Throws the gate's own sentence — which names the consent route when one exists here, says plainly
+ * that there is none when it does not, names the granted tool when the account is already lent, and
+ * asks which account was meant when one sentence named both. Returns normally on every other turn,
+ * which is the ordinary path and is unchanged.
+ *
+ * 🔴 IT ALWAYS WRITES THE `connector.acting_identity` ROW, INCLUDING ON THE ORDINARY PATH. A trail
+ * that records only refusals cannot answer "which account read this page", which is the question
+ * OPE-1525 was filed for.
+ *
+ * 🔴 THE `install` CHECK IS STRUCTURAL, NOT DECORATION. The gate's contract is "refuse on `refusal`,
+ * otherwise run under `identity`" — and every caller of this helper goes on to resolve the
+ * DEPLOYMENT's credential, which is the `install` identity and the only one it can spend. Reading
+ * only the refusal would keep that contract by convention: the day a caller passes
+ * `callerCanSpendPersonal`, the gate would return `identity: "human-acting"`, this helper would
+ * return normally, and the read would run on the install key — the exact OPE-1525 defect, re-entered
+ * through the fix for it. So the precondition is asserted here rather than remembered.
+ */
+export declare function assertNotionActingIdentity(ctx: BindableContext, tool: string): Promise<void>;
+//# sourceMappingURL=notion-acting-identity.d.ts.map

package/dist/agent/channels/notion-acting-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-acting-identity.d.ts","sourceRoot":"","sources":["../../../agent/channels/notion-acting-identity.ts"],"names":[],"mappings":"AAwCA,OAAO,EAAuD,KAAK,eAAe,EAAyB,MAAM,4CAA4C,CAAC;AAa9J;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAclG"}