@theronap/cortex-mcp 0.9.115 → 0.9.117

package/lib/server.mjs

@@ -1698,6 +1698,90 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'split_page',
+    {
+      title: 'Move sections onto a new child page',
+      description: 'SPLIT a page: move whole sections onto a NEW page, leaving the original in place. Use it when a page has grown past what can be read in one turn — that is a correctness problem, not just a cost one, because an agent that cannot read the whole authority answers from part of it (a head page and its governing page disagreed about a gate status for a week that way). Measured across 480 pages: the median page is ~3,500 chars, but 5.2% of pages hold a third of all authored text, so this is a targeted tool for the tail, not routine hygiene. It does NOT make pages go wrong less often — corrections scale roughly linearly with size — it changes what each correction COSTS to make: fixing one claim on a 165k-char page means reading ~42,000 tokens; on a 20k child, ~5,000. WHAT IT NEVER DOES, each for a measured reason: it never retires the original (a split is 1→2 and `superseded_by` holds one successor, so naming one would be false; the original also keeps receiving traffic that has no narrower match); it never moves governance (attaching a record to the child does not change its tier — reassigning governance is a privacy act and stays separate); it never rewrites inbound [[links]] (the splitter cannot know which half a link meant, the reader following it does — so the child says where it came from and lets them decide); and it never adds a link on the SOURCE, because where that link goes is prose — the response tells you to add one. GUARDS: the child is created BEFORE the source is trimmed, so a mid-way failure duplicates sections rather than losing them; `headings` must match the STORED heading exactly, INCLUDING any `· as of <date>` suffix (the rendered page can show a second `as of` stamp that is not part of it); moving every section is refused as a rename; and a child STRICTER than its parent is refused outright, because access is the union of attachments capped by the governing page — records attached to a stricter child keep their audience through the original, so it would look private while its evidence stayed readable. The child inherits the parent tier and its access grants, and gets an `In short` section rather than a summary. Fully reversible: `page_history` + `rollback_page` restore the source, and the child can be retired.',
+      inputSchema: {
+        name: z.string().describe('the exact page name to split, as read_page shows it'),
+        headings: z.array(z.string()).min(1).describe('the headings of the sections to MOVE, matched EXACTLY against the stored heading — include any `· as of <date>` suffix. Everything not listed stays on the original.'),
+        new_title: z.string().describe('the title of the new child page. It must not already exist in this brain.'),
+        base_version: z.string().describe('the `version` read_page prints for the SOURCE page (64-hex). REQUIRED — it is the concurrency check AND how the right brain is resolved.'),
+        reason: z.string().describe('WHY you are splitting, in one short phrase — recorded in page_history. Say what outgrew the page.'),
+        owner: z.string().optional().describe('user id to own the child. Defaults to you, and the response says so when it does — worth setting deliberately, because ownership transfer has no reachable path once an owner is deactivated.'),
+        tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('omit to COPY the source page tier, which is almost always right. A LOOSER tier is a deliberate widening; a STRICTER one is refused, since a split cannot tighten access.'),
+      },
+    },
+    async ({ name, headings, new_title, base_version, reason, owner, tier }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/split-page`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            name, headings, new_title, base_version, reason,
+            ...(owner ? { owner } : {}), ...(tier ? { tier } : {}),
+          }),
+        })
+      } catch (e) {
+        return toolError(`Could not split the page: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        // `child_created` + `remaining` is the one failure worth reading carefully: it means the split
+        // is HALF DONE and nothing was lost. Surface it first so the caller finishes rather than retries
+        // from the top, which would 409 on the now-taken title and look like a different problem.
+        const extra = [
+          out?.child_created ? `the child "${out.child_created}" EXISTS and holds every moved section — nothing was lost` : '',
+          Array.isArray(out?.remaining) ? `still on BOTH pages, re-run for these: ${out.remaining.join(' · ')}` : '',
+          Array.isArray(out?.detail) ? `detail: ${out.detail.join(' · ')}` : '',
+          out?.message ?? '',
+        ].filter(Boolean).join('\n')
+        const hint = out?.hint ? `\n${out.hint}` : ''
+        return toolError(`Could not split "${name}": ${out?.error ?? res.status}${extra ? `\n${extra}` : ''}${hint}`)
+      }
+      const ownerNote = out.owner_defaulted
+        ? '\n⚠ The child is owned by you because no `owner` was given. Set one deliberately if it should belong to someone else — transfer is unreachable once an owner is deactivated.'
+        : ''
+      const grants = out.grants_copied ? ` ${out.grants_copied} access grant(s) copied.` : ''
+      return { content: [{ type: 'text', text: `Split "${name}" (${out.brain} · ${out.tier} tier) → new page "${out.child}". Moved: ${out.moved.join(' · ')}.${grants} Child version: ${out.version}\n${out.note}\nNEXT: ${out.next}${ownerNote}\nReversible: \`page_history "${name}"\` then \`rollback_page\` restores the source; the child can be retired with set_page_validity.` }] }
+    },
+  )
+
+  server.registerTool(
+    'snooze_routing_claim',
+    {
+      title: 'Stop surfacing one unclaimed source',
+      description: "Silence one identifier in the `Sources nothing has claimed` block at session start. Use it when a recurring source genuinely belongs nowhere — a scratch repo, a bot channel, someone else's project that happens to cc you. NOT for something you simply have not got to yet: that is what leaving it alone does. A snooze silences the NOTICE and routes nothing; the events keep landing exactly where they land today. The block already has a volume floor that keeps one-off identifiers out, so anything you see there is recurring by construction — which is precisely why no threshold can tell 'not yet decided' from 'decided: nowhere', and why this exists. Bounded to at most a year and defaulting to 90 days, because a repo that was noise in August may be the centre of the work by November. Identity namespaces (`email:`, `thread:`) are refused: they are never surfaced as claimable in the first place, so there is nothing to snooze.",
+      inputSchema: {
+        identifier: z.string().describe('the identifier exactly as the context block prints it, e.g. `repo:owner/name`'),
+        brain: z.string().optional().describe('which brain to stop surfacing it in. Required when you belong to more than one — the call refuses rather than picking.'),
+        days: z.number().optional().describe('how long to stay quiet (1-365, default 90).'),
+        reason: z.string().optional().describe('why it belongs nowhere, in one phrase — the next person to see it resurface will want this.'),
+      },
+    },
+    async ({ identifier, brain, days, reason }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/snooze-routing-claim`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ identifier, ...(brain ? { brain } : {}), ...(days ? { days } : {}), ...(reason ? { reason } : {}) }),
+        })
+      } catch (e) {
+        return toolError(`Could not snooze ${identifier}: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        const extra = Array.isArray(out?.brains) ? `\nyour brains: ${out.brains.join(' · ')}` : ''
+        const hint = out?.hint ? `\n${out.hint}` : ''
+        return toolError(`Could not snooze ${identifier}: ${out?.error ?? res.status}${extra}${hint}`)
+      }
+      return { content: [{ type: 'text', text: `${out.note}\nIf it should route somewhere after all, \`set_routing_identifier\` on the owning page overrides this — a claim always beats a snooze.` }] }
+    },
+  )
+
   server.registerTool(
     'set_summary',
     {

package/package.json

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