@theronap/agnoclast-mcp 0.9.193 → 0.9.195

package/lib/seat_charge.mjs

@@ -0,0 +1,36 @@
+// A brain that pays for its members' seats (ADR-0072) refuses a member-add until the NEW monthly
+// total has been confirmed: POST /api/invite answers 409 with
+//   { code: 'seat_charge_unconfirmed', seatMonthlyTotal, seats, error }.
+// The confirmation is a recurring charge on the brain owner's card, so the tool must be able to tell
+// this apart from every other refusal and put the question to the person instead of reporting an
+// error. Pure, so it can be tested without a server.
+
+/**
+ * @param {number} status HTTP status of the refused add
+ * @param {string} raw the response body, unparsed
+ * @returns {{ total: number, seats: number | null } | null} null for any other refusal
+ */
+export function seatChargeRefusal(status, raw) {
+  if (status !== 409) return null
+  let body
+  try { body = JSON.parse(raw) } catch { return null }
+  if (!body || body.code !== 'seat_charge_unconfirmed') return null
+  const total = body.seatMonthlyTotal
+  // No usable number means there is nothing a person could confirm; fall through to the plain error
+  // rather than ask them to agree to "$undefined/month".
+  if (typeof total !== 'number' || !Number.isFinite(total) || total < 0) return null
+  const seats = typeof body.seats === 'number' && Number.isFinite(body.seats) ? body.seats : null
+  return { total, seats }
+}
+
+/** What the caller is told. `confirmed` is the total it passed, if any — then that total was stale. */
+export function seatChargeQuestion({ brainName, email, total, seats, confirmed }) {
+  return [
+    `${brainName} pays for its members' seats, so adding ${email} changes what its owner is charged.`,
+    `New total: $${total}/month${seats ? ` for ${seats} ${seats === 1 ? 'seat' : 'seats'}` : ''} ($10/month for each member), charged to the brain's owner.`,
+    ...(typeof confirmed === 'number' ? [`The total you confirmed ($${confirmed}) is not the current one — the membership changed in between.`] : []),
+    '',
+    'NOTHING HAS HAPPENED: nobody was added and nothing was charged.',
+    `Ask the user whether to accept $${total}/month. Only if they say yes, re-run with the same arguments plus confirm_seat_total: ${total}. Do not confirm it on their behalf.`,
+  ].join('\n')
+}

package/lib/server.mjs

@@ -5,6 +5,7 @@ import { writeFileSync, mkdirSync, readFileSync, statSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { createHash, randomUUID } from 'crypto'
+import { seatChargeRefusal, seatChargeQuestion } from './seat_charge.mjs'
 import { fetchCortex, classify, resolveBase, resolveEnvToken, setSessionKey, setClientVersion, runWithTool, heartbeatPolicy } from './diagnose.mjs'
 import { REPORT_KINDS, REPORT_ISSUE_DESCRIPTION, fileIssue } from './report_issue.mjs'
 import { folderClaimLine } from './folder_claims.mjs'
@@ -559,7 +560,7 @@ function renderNudge(payload) {
         title: z.string().optional().describe('short title for the session'),
         sessionId: z.string().optional().describe('the Claude Code session id — DEFAULTS to the current session, so omit it unless you are logging on behalf of another one. It is shared by every segment and the only thing pairing them, and it is also the join to the pages this session wrote (page_revisions.session_key); without it the record is unattributable forever, since the fallback dedupe key is a timestamp. Deliberately NOT a link: segments never reference each other, so a reader cleared for one brain cannot tell the others exist, while you can join on it across brains'),
         brain: z.string().optional().describe('which brain to record this session in (name or org id, one of your own). REQUIRED IN EFFECT for a multi-brain member: session-class sources route only by an explicit brain or a sole membership, so omitting it stages the log instead of recording it.'),
-        privacy: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('tier this record AT WRITE TIME. Use when the summary names confidential work (a candidate evaluation, a security finding) — safer than letting it land org-visible and re-tiering after, which leaves it readable in between.'),
+        privacy: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('tier this record AT WRITE TIME. A record is normally read by whoever can read the page it is filed under. Pass "confidential" when the summary names confidential work (a candidate evaluation, a security finding) so it is yours alone from the start — safer than letting it land page-visible and locking it after, which leaves it readable in between. Pass "scoped" to lock it to you and your managers. OMIT it for ordinary work: the record then follows its page, which is what makes it visible to the people working on that page with you.'),
       },
     },
     async ({ summary, segments, project, title, sessionId, brain, privacy }) => {
@@ -3900,7 +3901,7 @@ function renderNudge(payload) {
     'add_to_brain',
     {
       title: 'Add someone to one of your brains',
-      description: "Add a person to one of your brains, or work out what it would take. Resolves which brain, whether you may add to it, and the manager id they are placed under. WITHOUT execute:true it only reports the plan and hands back a console link — call it that way first and show the user what you are about to do. WITH execute:true it performs the add, and then `brain` is REQUIRED: an access grant must never be aimed by a shared write pointer. Adding cannot be undone through the API. Use when asked to invite/add someone to a brain.",
+      description: "Add a person to one of your brains, or work out what it would take. Resolves which brain, whether you may add to it, and the manager id they are placed under. WITHOUT execute:true it only reports the plan and hands back a console link — call it that way first and show the user what you are about to do. WITH execute:true it performs the add, and then `brain` is REQUIRED: an access grant must never be aimed by a shared write pointer. Adding cannot be undone through the API. IF THE BRAIN PAYS FOR ITS MEMBERS' SEATS, adding someone raises its owner's monthly charge: the first execute is refused with the new total, you ASK THE USER whether to accept that charge, and only on a yes re-run with confirm_seat_total set to that number. Use when asked to invite/add someone to a brain.",
       inputSchema: {
         email: z.string().describe("the person's email address — the login their Agnoclast account is (or will be) on"),
         name: z.string().optional().describe('their full name; falls back to the email local-part'),
@@ -3909,9 +3910,10 @@ function renderNudge(payload) {
         brain: z.string().optional().describe('which brain, by name or org id. Optional when planning; REQUIRED with execute:true. Pass the org id when a name matches more than one of your brains'),
         execute: z.boolean().optional().describe('default false. false = report the plan only. true = actually add them — not undoable through the API, and requires an explicit brain'),
         inherit_page_id: z.string().optional().describe("an existing PERSON page in that brain that becomes their user page (ADR-0023). The plan lists candidates; ask the user which, or omit for a new page"),
+        confirm_seat_total: z.number().optional().describe("ONLY after an execute was refused because this brain pays for its members' seats: the new monthly total in dollars that the refusal named, and ONLY once the user has said yes to that charge in this conversation. Never guess it, never pass it on a first attempt — it puts a recurring charge on the brain owner's card"),
       },
     },
-    async ({ email, name, title, role, brain, execute, inherit_page_id }) => {
+    async ({ email, name, title, role, brain, execute, inherit_page_id, confirm_seat_total }) => {
       const addr = (email ?? '').trim().toLowerCase()
       if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(addr)) return toolError(`"${email}" does not look like an email address.`)
 
@@ -4003,13 +4005,29 @@ function renderNudge(payload) {
           done = await fetchCortex(`${BASE}/api/invite`, {
             method: 'POST',
             headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-            body: JSON.stringify({ ...payload, brain: target.orgId, ...(inherit_page_id ? { inheritPageId: inherit_page_id } : {}) }),
+            body: JSON.stringify({
+              ...payload,
+              brain: target.orgId,
+              ...(inherit_page_id ? { inheritPageId: inherit_page_id } : {}),
+              // ADR-0072 §3.5. Sent only when the caller passed it: the server compares it with the
+              // total THIS add produces and refuses anything else, so a stale or invented number
+              // cannot charge anyone.
+              ...(typeof confirm_seat_total === 'number' ? { confirmSeatTotal: confirm_seat_total } : {}),
+            }),
           })
         } catch (e) {
           return toolError(`Could not add ${payload.email} to ${target.name}: ${e.message}`)
         }
         if (!done.ok) {
-          const d = classify(done.status, done.headers.get('content-type'), await done.text(), done.headers.get('x-vercel-id'))
+          const raw = await done.text()
+          // A brain that pays for its members' seats refuses the add until the new monthly total is
+          // confirmed (ADR-0072 §3.5). That is not a failure to report and move on from — it is a
+          // question only the person can answer, because the answer is a charge on the owner's card.
+          const seat = seatChargeRefusal(done.status, raw)
+          if (seat) {
+            return toolError(seatChargeQuestion({ brainName: target.name, email: payload.email, total: seat.total, seats: seat.seats, confirmed: confirm_seat_total }))
+          }
+          const d = classify(done.status, done.headers.get('content-type'), raw, done.headers.get('x-vercel-id'))
           return toolError(`Could not add ${payload.email} to ${target.name}: ${d.message}`)
         }
         const r = await done.json().catch(() => ({}))
@@ -4024,7 +4042,10 @@ function renderNudge(payload) {
         const page = r.userPage?.status
           ? `\nTheir page in ${target.name}: ${r.userPage.status}${r.userPage.error ? ` (${r.userPage.error})` : ''}.`
           : ''
-        return { content: [{ type: 'text', text: `Added ${payload.name} <${payload.email}> to ${target.name} as ${payload.role}, placed under you.\n${how}${page}\n\nThis cannot be undone through the API — removing a membership currently needs direct database access.` }] }
+        // What the seat sync did, in the server's words: the new monthly total, or that the seat
+        // could NOT be charged and the brain is not paying for them yet.
+        const seatLine = typeof r.seatNote === 'string' && r.seatNote ? `\n${r.seatNote}` : ''
+        return { content: [{ type: 'text', text: `Added ${payload.name} <${payload.email}> to ${target.name} as ${payload.role}, placed under you.\n${how}${page}${seatLine}\n\nThis cannot be undone through the API — removing a membership currently needs direct database access.` }] }
       }
 
       // ADR-0023: does this brain already have a page about them? The inviter decides — list, never pick.
@@ -4052,6 +4073,8 @@ function renderNudge(payload) {
         `  manager    you  [${target.userId}]  (they are placed under you)`,
         ...pageLines,
         '',
+        "If this brain pays for its members' seats, the first execute is refused with the new monthly total; ask the user before confirming it.",
+        '',
         'Nothing has happened yet. To go ahead, re-run with execute:true and the same brain —',
         `or do it yourself at ${BASE}/?invite=1 with these values:`,
         '',
@@ -4404,10 +4427,10 @@ function renderNudge(payload) {
     'set_record_privacy',
     {
       title: 'Set a record\'s privacy tier',
-      description: 'Reclassify the access tier of one of YOUR OWN records: "accessible" (anyone in the org), "scoped" (you + your management chain), or "confidential" (you + people you explicitly grant access). Get record_id from a `list_records` result or the "id:" on a `my_context` activity line. Only affects records you own — others return an error.',
+      description: 'Lock or release one of YOUR OWN records. A record is read by whoever can read the PAGE it is filed under; this is how you make one tighter than its page, or let it follow its page again. "accessible" = no lock, the record follows its page · "scoped" = locked to you and your managers, within the page\'s audience · "confidential" = you only, plus people you explicitly grant. Naming a tier IS the deliberate act: setting "scoped" on a record that already reads scoped locks it (most records are born scoped by default, which restricts nothing). Session summaries captured before 2026-10-01 are locked at scoped until you release them with "accessible". A record filed under no page is yours alone whatever its tier. Get record_id from a `list_records` result or the "id:" on a `my_context` activity line. Only affects records you own — others return an error.',
       inputSchema: {
         record_id: z.string().describe('the record id (uuid), e.g. the "id:" on a list_records line'),
-        privacy: z.enum(['accessible', 'scoped', 'confidential']).describe('the new access tier'),
+        privacy: z.enum(['accessible', 'scoped', 'confidential']).describe('accessible = follow the page (no lock); scoped = lock to you + your managers; confidential = you only'),
       },
     },
     async ({ record_id, privacy }) => {
@@ -5069,7 +5092,7 @@ function renderNudge(payload) {
     'set_page_privacy',
     {
       title: 'Change who can see a wiki page',
-      description: `Re-tier a wiki page you own or may edit. ${PAGE_TIER_GLOSS}. Every tier but confidential is also readable by the page owner's managers. ⚠ reports / peers / down are RELATIVE TO THE PAGE'S OWNER, computed live: the audience is the OWNER's team, it changes when the owner moves in the org chart or the page is transferred, and ONLY the owner can move a page to or from one of them. They never change a record — records filed under the page are read by that same audience, each still capped by its own tier. Demoting a PROJECT page to scoped or confidential also demotes its evidence records (demote-only; each record's owner is notified and can revert). Promotions never touch records. Org admins may narrow any page to scoped or confidential, never widen.`,
+      description: `Re-tier a wiki page you own or may edit. ${PAGE_TIER_GLOSS}. Every tier but confidential is also readable by the page owner's managers. ⚠ reports / peers / down are RELATIVE TO THE PAGE'S OWNER, computed live: the audience is the OWNER's team, it changes when the owner moves in the org chart or the page is transferred, and ONLY the owner can move a page to or from one of them. RECORDS FOLLOW THE PAGE: a record filed under a page is read by whoever can read that page, so widening a page widens its records and narrowing it narrows them — except a record its owner locked (set_record_privacy) or made confidential, which stays tighter. Demoting a PROJECT page to scoped or confidential also rewrites its evidence records' own tier to match (each record's owner is notified and can revert). Org admins may narrow any page to scoped or confidential, never widen.`,
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the page kind'),
         name: z.string().optional().describe('the exact page name (or pass `ref` instead — one of the two is required)'),

package/package.json

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