@theronap/agnoclast-mcp 0.9.232 → 0.9.234

package/lib/locked_tools.mjs

@@ -0,0 +1,102 @@
+// AGNOCLAST LITE — LOCKED TOOLS on the stdio server (Theron, 2026-10-13 3:19 PM MDT: "What if we stopped the
+// agent from using the tools but we did allow them to see that the tools are there as something that would be
+// open to them if they either used the trial or paid for the plan?").
+//
+// The list, the 🔒 line and every answer live on the server (web/lib/engine/locked_tools.ts) so the claude.ai
+// connector and this server can never disagree. This module only:
+//   · asks once at start-up whether this account is locked (GET /api/lite/locked), and marks those tools'
+//     descriptions with the server's 🔒 line before the first tools/list goes out — the rest of each
+//     description is left exactly as written;
+//   · for a call to a locked tool, asks the server for the answer (POST /api/lite/locked) and returns it
+//     INSTEAD of running the tool. If the server now says "not locked" (the trial started mid-session), the
+//     tool runs as usual.
+//   · FAILS CLOSED when it cannot know (Codex review, 2026-10-13): if start-up could not learn the account's
+//     state, every tool in REGULAR_ONLY_TOOLS asks per call, and a call whose check cannot be made runs
+//     nothing and says so. A definite "not locked" (Regular) at start-up costs nothing per call.
+
+/**
+ * The fallback list, used only when start-up could not ask the server. The same names as the server's
+ * LOCKED_TOOLS (web/lib/engine/locked_tools.ts) that exist here — web/lib/engine/trial.test.ts pins the two.
+ */
+export const REGULAR_ONLY_TOOLS = [
+  'list_records', 'read_record', 'timeline_pull', 'record_status', 'set_record_notes', 'set_record_privacy',
+  'relabel_record_people', 'supersede_record', 'move_record', 'contain_record', 'pending_records', 'claim_record',
+  'route_record', 'unroute_record', 'request_file', 'get_file', 'create_custom_source', 'search_spam_email',
+  'gmail_modify', 'draft_email_reply', 'request_send_email', 'send_imessage', 'create_brain', 'add_to_brain',
+]
+
+/** What a locked tool answers when the check itself could not be made. Nothing was run. */
+export const LOCK_CHECK_FAILED =
+  'Not run: this tool is part of the Agnoclast Regular plan, and Agnoclast did not answer whether this account can use it right now, ' +
+  'so nothing was done. Try again in a moment.'
+
+/** Start-up budget: the MCP handshake must not wait on this for long. */
+export const LOCK_FETCH_TIMEOUT_MS = 2500
+
+/**
+ * GET /api/lite/locked → { known: true, locked: false } (Regular, or a server that predates locked tools: a
+ * 404) | { known: true, locked: true, tools, lockLine } | { known: false, locked: false } (no answer). Never throws.
+ */
+export async function fetchLockState(base, token, fetchImpl) {
+  try {
+    const res = await fetchImpl(`${base}/api/lite/locked`, { headers: { Authorization: `Bearer ${token}` } }, { skipAutofile: true })
+    if (res.status === 404) return { known: true, locked: false }
+    if (!res.ok) return { known: false, locked: false }
+    const j = await res.json()
+    if (j?.locked === false) return { known: true, locked: false }
+    if (j?.locked !== true || !Array.isArray(j.tools) || typeof j.lockLine !== 'string') return { known: false, locked: false }
+    return { known: true, locked: true, tools: j.tools.filter((t) => typeof t === 'string'), lockLine: j.lockLine }
+  } catch {
+    return { known: false, locked: false }
+  }
+}
+
+/** The lock state, or "unknown" if it did not arrive within the budget. */
+export async function lockStateWithin(promise, ms = LOCK_FETCH_TIMEOUT_MS) {
+  let timer
+  const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve({ known: false, locked: false }), ms) })
+  try { return await Promise.race([promise, timeout]) } finally { clearTimeout(timer) }
+}
+
+/**
+ * Which registered tools must ask before they run, marking the locked ones' descriptions (lockLine + the
+ * original). Locked → the server's list. Unknown → REGULAR_ONLY_TOOLS, unmarked (we do not know they are
+ * locked; each call asks). Regular → none. `handles` maps a name to { handle, description }.
+ */
+export function applyLock(handles, lock) {
+  const checked = new Set()
+  if (lock?.known === false) {
+    for (const name of REGULAR_ONLY_TOOLS) if (handles.has(name)) checked.add(name)
+    return checked
+  }
+  if (!lock?.locked) return checked
+  for (const name of lock.tools) {
+    const h = handles.get(name)
+    if (!h) continue
+    h.handle.update({ description: `${lock.lockLine}${h.description ?? ''}` })
+    checked.add(name)
+  }
+  return checked
+}
+
+/**
+ * POST /api/lite/locked { tool, args } → { run: true } to run the tool as usual, or { run: false, text } to
+ * answer instead. A check that cannot be made answers LOCK_CHECK_FAILED: nothing runs. Never throws.
+ */
+export async function lockedAnswerFor(base, token, tool, args, fetchImpl) {
+  try {
+    const res = await fetchImpl(`${base}/api/lite/locked`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ tool, args: args && typeof args === 'object' && !Array.isArray(args) ? args : {} }),
+    }, { skipAutofile: true })
+    if (res.status === 404) return { run: true }   // a server that predates locked tools locks nothing
+    if (!res.ok) return { run: false, text: LOCK_CHECK_FAILED }
+    const j = await res.json()
+    if (j?.locked === false) return { run: true }
+    if (j?.locked === true && typeof j.text === 'string') return { run: false, text: j.text }
+    return { run: false, text: LOCK_CHECK_FAILED }
+  } catch {
+    return { run: false, text: LOCK_CHECK_FAILED }
+  }
+}

package/lib/server.mjs

@@ -30,6 +30,8 @@ import { renderRecord, READ_RECORD_DEFAULT_CHARS, READ_RECORD_PARTS } from './re
 import { formatCreated, formatDryRun, formatSources, homeFromArgs, pickSource, renderHomeProblem } from './custom_sources.mjs'
 import { formatSeriesRefusal, formatSeriesUpdated } from './series_render.mjs'
 import { formatSends } from './sends_render.mjs'
+import { applyLock, fetchLockState, lockedAnswerFor, lockStateWithin } from './locked_tools.mjs'
+import { filterUnshownSettling } from './settling_shown.mjs'
 
 // PAGE tiers (ADR-0071). Six for a PAGE; a RECORD keeps three (`privacy` on log_session and
 // set_record_privacy below) — an owner-relative tier is applied to a page's records when they are read
@@ -387,11 +389,30 @@ export async function runServer(version) {
   }
 
   const server = new McpServer({ name: 'cortex', version })
+  // AGNOCLAST LITE — locked tools (lib/locked_tools.mjs; Theron, 2026-10-13 3:19 PM). Asked now, in parallel
+  // with registering ~120 tools, and awaited (bounded) just before the handshake, so the first tools/list a
+  // Lite account's AI sees already marks the Regular-only tools 🔒. Regular accounts: nothing changes.
+  const lockP = fetchLockState(BASE, TOKEN, fetchCortex)
+  const toolHandles = new Map()
+  let lockedTools = new Set()
   // ADR-0070: every tool runs with its NAME in async context, so an outage fetchCortex auto-files is
   // attributed to the tool that hit it rather than guessed from a URL shared by several tools.
   const registerTool = server.registerTool.bind(server)
-  server.registerTool = (name, config, handler) =>
-    registerTool(name, config, (...args) => runWithTool(name, () => handler(...args)))
+  server.registerTool = (name, config, handler) => {
+    const takesArgs = !!config?.inputSchema
+    const handle = registerTool(name, config, (...args) => runWithTool(name, async () => {
+      // A LOCKED tool runs nothing: the server's answer says what it would have done and how Regular is
+      // reached. "Not locked any more" (the trial started mid-session) → the tool runs as usual; a check that
+      // cannot be made → nothing runs (fails closed).
+      if (lockedTools.has(name)) {
+        const check = await lockedAnswerFor(BASE, TOKEN, name, takesArgs ? args[0] : {}, fetchCortex)
+        if (!check.run) return { content: [{ type: 'text', text: check.text }] }
+      }
+      return handler(...args)
+    }))
+    toolHandles.set(name, { handle, description: config?.description })
+    return handle
+  }
 
 
 // ── THE PRE-CLAIM NUDGE, rendered ───────────────────────────────────────────────────────────────
@@ -430,9 +451,18 @@ function renderArrival(payload) {
     ` — \`staged_records\` lists them. Not offered to you, just counted; \`ignore_arrivals\` if this is noise right now.`
 }
 
+// ASK ONCE, THEN ONLY WHAT IS NEW (Theron, 2026-10-14). This block rode on EVERY tool reply, unchanged,
+// and an offer that can be ignored on every call is ignored on every call — measured that day: 869
+// pending, 0 claimed, while the block was printed to every session. Now a unit is shown to this process
+// (one MCP server = one session) the first time only, framed as a decision owed before other work.
+// Units every session passes on are escalated to the PERSON at the next session start
+// (web/lib/engine/orphan_escalation.ts), so a unit dropped here is never lost — it changes audience.
+const settlingShown = new Set()
+
 function renderSettling(payload) {
   const feed = payload?.settling
-  const offers = Array.isArray(feed?.offers) ? feed.offers : []
+  const firstSight = settlingShown.size === 0
+  const offers = filterUnshownSettling(Array.isArray(feed?.offers) ? feed.offers : [], settlingShown)
   if (!offers.length) return ''
   const total = Number(feed?.total ?? offers.length)
 
@@ -463,7 +493,10 @@ function renderSettling(payload) {
     ? `\n— ⚠ ${maxHolders} live sessions of yours hold a matching identifier, so these are offered to all of them. \`intake_claim\` takes a lease — claim before you work, not after, or two sessions judge the same arrival.`
     : ''
 
-  return `\n\n⚡ ARRIVALS SETTLING — yours alone, and no one else can see these yet:\n${lines.join('\n')}\n` +
+  const head = firstSight
+    ? `\n\n⚡ ARRIVALS SETTLING — DECIDE EACH LINE BEFORE CONTINUING: \`intake_claim\` it if it belongs to this session's work, otherwise \`not_mine\`. You are asked once; when every session has passed, the person is told at the next session start.\n`
+    : `\n\n⚡ NEW ARRIVALS SETTLING — decide each: \`intake_claim\` or \`not_mine\`:\n`
+  return `${head}${lines.join('\n')}\n` +
     `— These are unjudged ARRIVALS, not records. Since automatic materialization was deleted, nothing files them for you.\n` +
     `— \`intake_look <id>\` reads the full body without claiming it — looking is free, non-exclusive and logged, so look rather than guess from the headline.\n` +
     `— Then \`intake_claim {intakeItemIds: ["<id>"]}\` to take a lease on THAT unit (the array is required; without an id you claim the head of the queue instead), then \`intake_materialize\` into the brain and pages it belongs to — or \`intake_discard\`, or \`intake_defer\` with a question when only the owner can decide.\n` +
@@ -6710,5 +6743,6 @@ function renderNudge(payload) {
     },
   )
 
+  lockedTools = applyLock(toolHandles, await lockStateWithin(lockP))
   await server.connect(new StdioServerTransport())
 }

package/lib/settling_shown.mjs

@@ -0,0 +1,9 @@
+// Ask-once filter for the ⚡ ARRIVALS SETTLING block (2026-10-14). Pure, so it is testable without
+// importing server.mjs. An offer is fresh if ANY id it stands for has not been shown to this session;
+// a text conversation counts as one offer carrying many ids, so one new text re-raises its chat.
+export function filterUnshownSettling(offers, shown) {
+  const idsOf = (x) => (x.conversation?.ids?.length ? x.conversation.ids : [x.intakeItemId])
+  const fresh = offers.filter((x) => idsOf(x).some((id) => !shown.has(id)))
+  for (const x of fresh) for (const id of idsOf(x)) shown.add(id)
+  return fresh
+}

package/package.json

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