@theronap/cortex-mcp 0.9.115 → 0.9.116

package/lib/server.mjs

@@ -1698,6 +1698,57 @@ 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(
     'set_summary',
     {

package/package.json

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