@theronap/agnoclast-mcp 0.9.151 → 0.9.152

package/lib/server.mjs

@@ -78,6 +78,33 @@ export const sectionCurrencyStamp = (s, day) => {
 // invisible on exactly the sections that were healthy.
 export const renderSection = (s, day) => `### ${s.heading}${sectionCurrencyStamp(s, day)}\n${s.body}`
 
+/**
+ * ADR-0062 §5.1. A materialize PREVIEW goes to its own route: a server too old to know it answers 404,
+ * where /api/intake/materialize would ignore a `mode` it does not know and publish.
+ */
+export function intakeMaterializePath(mode) {
+  return mode === 'preview' ? '/api/intake/preview' : '/api/intake/materialize'
+}
+
+/** ADR-0062 §5.2. Which page governs a materialized record, and who chose it — or '' for an older server. */
+export function renderGoverningLine(governing) {
+  if (!governing || typeof governing !== 'object') return ''
+  const name = governing.title || 'a page'
+  const who = governing.designatedBy === 'session' ? 'chosen by you'
+    : governing.designatedBy === 'human' ? 'chosen by a person'
+    : 'chosen by the ranking — pass governingPage to decide it yourself'
+  return `Governed by ${name} (${governing.tier}) — ${who}.`
+}
+
+/** The one line a preview leads with, so it cannot be mistaken for a publish. */
+export function renderIntakePreviewLine(body) {
+  const p = (body && typeof body === 'object' && body.placement) || {}
+  const pages = Array.isArray(p.pages) ? p.pages.length : 0
+  const g = p.governing
+  const gov = g ? `${g.title || g.kind} (${g.tier})${p.governingJudged ? ', your choice' : ''}` : 'none'
+  return `PREVIEW — nothing was written. Would attach ${pages} page(s); governing: ${gov}; born ${p.tier ?? 'unknown'}.`
+}
+
 // TOP-OF-PAGE NOTES — ADR-0065's size note, and ADR-0064 §3's "Also visible to you" callout.
 //
 // ⚠ PRINTED VERBATIM, NEVER COMPOSED HERE. The server decides whether a note fires and what it says
@@ -88,6 +115,11 @@ export const renderSection = (s, day) => `### ${s.heading}${sectionCurrencyStamp
 // it from offset 0, so the footer of a huge page is the part nobody reaches — and these notes exist for
 // exactly those pages. Shared by read_page and project_status so the two cannot drift, which is how every
 // earlier fix to this file's page rendering landed on one surface and not the other.
+// v1 SCOPE (Theron, 2026-09-16): page splitting moves to v2 and the server refuses it with
+// `splitting_unavailable`. split_page is not registered, so agents do not see a verb that can only refuse.
+// The definition stays for v2: flip this together with the server's SPLITTING_AVAILABLE.
+export const SPLIT_PAGE_TOOL_AVAILABLE = false
+
 export const renderHeaderNotes = (notes) => {
   const lines = (Array.isArray(notes) ? notes : [])
     .filter((n) => typeof n === 'string' && n.trim() !== '')
@@ -877,7 +909,8 @@ function renderNudge(payload) {
     {
       title: 'Claim private intake items',
       description:
-        'Claim a lease on private intake items (relevance or cleanup). Returns decrypted payloads for the lease holder only. Requires x-cortex-session-key (set automatically by this MCP server). Aged work never blocks a claim: the response reports cleanupDueCount and how far behind the oldest unit is, and servicing it is expected but always your call. Claiming is a commitment to process — hand back anything you will not finish with intake_release, or intake_defer if it is the owner\'s decision to make.',
+        'Claim a lease on private intake items (relevance or cleanup). Returns decrypted payloads for the lease holder only. Requires x-cortex-session-key (set automatically by this MCP server). Aged work never blocks a claim: the response reports cleanupDueCount and how far behind the oldest unit is, and servicing it is expected but always your call. Claiming is a commitment to process — hand back anything you will not finish with intake_release, or intake_defer if it is the owner\'s decision to make. ' +
+        'YOU ARE THE JUDGE of every unit you claim (ADR-0062): nothing is published until you materialize, and materializing is when it becomes visible. Each unit carries a `proposal` — the brain its signals point to and, for that brain, the pages it would attach to, the page that would govern it, and the `tier` it would be born with — computed without writing anything. Decide the brain, the pages (confirm, drop or add), which page should govern (the page whose reasons for restricting its audience fit the content, not a person page), and obligations. Pages only tighten a tier; if a record should be LOOSER than `tierReason.baseline`, that is the owner\'s call — intake_defer with the question.',
       inputSchema: {
         claimKind: z.enum(['relevance', 'cleanup']).optional().describe('default relevance'),
         limit: z.number().optional().describe('max items (default 10). Ignored when intakeItemIds is given.'),
@@ -947,7 +980,9 @@ function renderNudge(payload) {
     {
       title: 'Materialize a private intake item',
       description:
-        'Atomically publish a claimed intake item into one brain. Deterministic identifier homes in that brain are always attached; documentIds may add further pages. Sets record confidentiality to the strictest attached page tier. Never writes private intake into search/history before this call.',
+        'Atomically publish a claimed intake item into one brain — the disclosure moment (ADR-0062). Deterministic identifier homes in that brain are always attached; documentIds may add further pages. The record is born at the strictest of its source baseline, what the producer asked for, and every attached page; a source floor (iMessage, claude-code) pins it. ' +
+        'Name the governing page with governingPage (one of documentIds, never a person page) — otherwise the ranking picks it. ' +
+        'Pass mode "preview" first when your choice differs from the claim\'s proposal: it returns the pages, the governing page and the tier this exact call would produce, and writes nothing. Never writes private intake into search/history before this call.',
       inputSchema: {
         intakeItemId: z.string().describe('intake item uuid'),
         orgId: z.string().describe('destination brain org uuid'),
@@ -958,10 +993,21 @@ function renderNudge(payload) {
         recordType: z.string().optional(),
         dedupeKey: z.string().optional(),
         origin: z.enum(['deterministic', 'llm', 'user', 'session']).optional(),
+        governingPage: z.string().optional().describe(
+          'the page that should GOVERN this record (ADR-0062) — a page `ref:` or document id, and one of documentIds. ' +
+          'Choose the page whose reasons for restricting its audience fit the content; never a person page. It can only ' +
+          'tighten the record, and the ranking will not move it. Omit to leave the choice to the ranking.',
+        ),
+        mode: z.enum(['preview', 'apply']).optional().describe(
+          '"preview": report the pages, governing page and tier this call would produce, and write nothing. Default "apply".',
+        ),
       },
     },
     async (args) => {
-      const res = await fetchCortex(`${BASE}/api/intake/materialize`, {
+      // A preview goes to its OWN route: a server too old to know it answers 404, where the materialize
+      // route would ignore a `mode` it does not know and publish.
+      const preview = args.mode === 'preview'
+      const res = await fetchCortex(`${BASE}${intakeMaterializePath(args.mode)}`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
         body: JSON.stringify({
@@ -976,13 +1022,20 @@ function renderNudge(payload) {
             dedupe_key: args.dedupeKey,
           },
           attachmentMeta: (args.documentIds ?? []).map(() => ({ origin: args.origin ?? 'llm' })),
+          ...(args.governingPage ? { governingDocumentId: args.governingPage } : {}),
         }),
       })
       if (!res.ok) {
         const body = await res.text()
+        if (preview && res.status === 404) {
+          return toolError('This server cannot preview a materialization yet — nothing was written. Materialize without mode, or wait for the server to update.')
+        }
         return toolError(body)
       }
       const body = await res.json()
+      if (preview) {
+        return { content: [{ type: 'text', text: `${renderIntakePreviewLine(body)}\n\n${JSON.stringify(body, null, 2)}` }] }
+      }
       // WHERE THE SESSION'S OWN WORK LANDED, in words rather than buried in the JSON dump.
       //
       // Three outcomes that look identical in raw JSON and mean completely different things:
@@ -999,6 +1052,8 @@ function renderNudge(payload) {
       // the ordinary case (observed 2026-09-03 on the first handoff record materialised). Silence is
       // correct here, and it also covers a server too old to send the field at all.
       const lines = []
+      const governingLine = renderGoverningLine(body?.governing)
+      if (governingLine) lines.push(governingLine)
       const sa = body?.sessionAttachments
       if (sa === null) {
         lines.push('⚠ Session-page attachment FAILED for this record — it was written, but not filed under the pages this session worked on. Re-run the reconciler.')
@@ -1880,7 +1935,7 @@ function renderNudge(payload) {
     },
   )
 
-  server.registerTool(
+  if (SPLIT_PAGE_TOOL_AVAILABLE) server.registerTool(
     'split_page',
     {
       title: 'Move sections onto a new child page',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/agnoclast-mcp",
-  "version": "0.9.151",
+  "version": "0.9.152",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {