@theronap/agnoclast-mcp 0.9.254 → 0.9.256

package/lib/intake_id_alias.mjs

@@ -0,0 +1,31 @@
+// ONE INTAKE UNIT ID, TWO SPELLINGS (2026-10-22).
+//
+// `not_mine` took `intake_item_id` while `intake_release` (and every other intake verb) took
+// `intakeItemId`. The schemas strip an unknown key, so the wrong spelling arrived as "missing" — one
+// session made 607 failing calls on 10-21/10-22 guessing between the two. Every intake verb now takes
+// BOTH spellings; when both are given they must agree, never silently pick one.
+
+/**
+ * PURE. The intake unit id from either spelling, or an error string.
+ * `required: false` lets a verb that also takes another kind of id (not_mine's record_id) accept neither.
+ */
+export function intakeIdFrom(args, { required = true } = {}) {
+  const camel = typeof args?.intakeItemId === 'string' ? args.intakeItemId.trim() : ''
+  const snake = typeof args?.intake_item_id === 'string' ? args.intake_item_id.trim() : ''
+  if (camel && snake && camel !== snake) {
+    return { error: `intakeItemId (${camel}) and intake_item_id (${snake}) disagree — pass one of them.` }
+  }
+  const id = camel || snake
+  if (!id && required) return { error: 'intakeItemId is required (intake_item_id is accepted too).' }
+  return { id: id || null }
+}
+
+/** intakeIdFrom for an expression-bodied handler: the id, or a thrown Error the SDK returns as a tool error. */
+export function requireIntakeId(args) {
+  const r = intakeIdFrom(args)
+  if (r.error) throw new Error(r.error)
+  return r.id
+}
+
+/** The zod description for the alias field, so every verb says the same thing. */
+export const INTAKE_ID_ALIAS_NOTE = 'same as intakeItemId — either spelling is accepted'

package/lib/server.mjs

@@ -25,6 +25,7 @@ import { renderObligations, renderPageObligations, tierReads, who } from './obli
 import { renderLeaveQuestion, renderLeft, renderRemovalQuestion, renderRemoved } from './member_remove_render.mjs'
 import { renderSettings } from './settings_render.mjs'
 import { renderConversationOffer, renderMaterializeBatch } from './intake_batch_render.mjs'
+import { intakeIdFrom, requireIntakeId, INTAKE_ID_ALIAS_NOTE } from './intake_id_alias.mjs'
 import { obligationsForUnits, renderFilingObligations, filingObligationsBrief, OBLIGATIONS_UNANSWERED_TEXT } from './filing_obligations.mjs'
 import { renderRecord, READ_RECORD_DEFAULT_CHARS, READ_RECORD_PARTS } from './record_render.mjs'
 import { formatCreated, formatDryRun, formatSources, homeFromArgs, pickSource, renderHomeProblem } from './custom_sources.mjs'
@@ -1204,9 +1205,14 @@ 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. ' +
-        '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.',
+        '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. ' +
+        'view "compact" (trial, only where the server enables it — otherwise you get the full response): the judge rules, your brains, the lease and the cleanup count come ONCE per response in `rules`/`brains`, not on every unit; each unit carries its full content, only the proposed brain\'s pages as one line each, and up front what intake_materialize would refuse it for (`materialize.otherHomes`, `materialize.folderQuestions`). Read `rules` before judging.',
       inputSchema: {
         claimKind: z.enum(['relevance', 'cleanup']).optional().describe('default relevance'),
+        view: z.enum(['full', 'compact']).optional().describe(
+          'default "full". "compact" sends the rules once per response instead of on every unit, and only the proposed ' +
+          'brain\'s placement. Honoured only where the server enables it; otherwise the response is the full one.',
+        ),
         limit: z.number().optional().describe('max items (default 10). Ignored when intakeItemIds is given.'),
         source: z.string().optional().describe('claim only the oldest units of ONE source — e.g. "imessage", "meeting", "email", "github", "claude-code". Reaches texts without first claiming every older GitHub/session unit ahead of them. Ignored when intakeItemIds is given.'),
         leaseMinutes: z.number().optional().describe('lease length in minutes, 5-60 (default 30). Prefer intake_look for read-only inspection — a short lease is only for briefly exclusive work.'),
@@ -1221,6 +1227,7 @@ function renderNudge(payload) {
           'a single unit to claim — the same thing as intakeItemIds with one element. Accepted because ' +
           'every other intake verb spells it this way.',
         ),
+        intake_item_id: z.string().optional().describe(INTAKE_ID_ALIAS_NOTE),
         intakeItemIds: z.array(z.string()).optional().describe(
           'claim these specific units instead of the head of the queue (max 50). Without it you get FIFO, ' +
           'so reaching one known unit means claiming everything ahead of it. Ids come from intake_changes ' +
@@ -1232,9 +1239,11 @@ function renderNudge(payload) {
         ),
       },
     },
-    async ({ claimKind, limit, source, intakeItemId, intakeItemIds, leaseMinutes }) => {
-      // Merge the two spellings before anything else looks at them. Passing both is not an error —
-      // the union is what the caller plainly meant.
+    async ({ claimKind, limit, source, intakeItemId, intakeItemIds, leaseMinutes, intake_item_id, view }) => {
+      // Merge the spellings before anything else looks at them. Passing both is not an error —
+      // the union is what the caller plainly meant. (intake_item_id: 2026-10-22, see intake_id_alias.mjs —
+      // dropped by the schema it would have meant a FIFO claim of the head of the queue.)
+      if (intake_item_id) intakeItemIds = [...(intakeItemIds ?? []), intake_item_id]
       const ids = [...new Set([...(intakeItemIds ?? []), ...(intakeItemId ? [intakeItemId] : [])])]
       intakeItemIds = ids.length ? ids : undefined
       const res = await fetchCortex(`${BASE}/api/intake/claim`, {
@@ -1250,6 +1259,8 @@ function renderNudge(payload) {
           // claim into a no-op.
           ...(intakeItemIds ? { intakeItemIds } : {}),
           ...(source ? { source } : {}),
+          // Sent only when asked for: a default claim's request body is exactly what it was.
+          ...(view === 'compact' ? { view } : {}),
         }),
       })
       if (!res.ok) {
@@ -1282,7 +1293,9 @@ function renderNudge(payload) {
               + `Nothing is blocked — run intake_claim with claimKind:"cleanup" when you reach a natural break.`
       }
 
-      return { content: [{ type: 'text', text: JSON.stringify(j, null, 2) + nudge }] }
+      // The compact view is printed without indentation — it is what the view is for. The full one, as before.
+      const text = j?.view === 'compact' ? JSON.stringify(j) : JSON.stringify(j, null, 2)
+      return { content: [{ type: 'text', text: text + nudge }] }
     },
   )
 
@@ -1294,19 +1307,21 @@ function renderNudge(payload) {
         '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. ' +
-        '⚠ ADR-0051: a unit does not finish until you looked for its OTHER homes. A call whose documentIds add nothing beyond the deterministic homes it gets anyway is REFUSED once — name the pages this unit is about (the design it implements, the project, the person), or go look, or say you looked with searchedForOtherHomes. ' +
+        '⚠ ADR-0051 — BEFORE you file, look for this unit\'s OTHER homes: the pages it is about beyond what an identifier matched (the design it implements, the project, the person, the decision it bears on). grep or read for them, then name them in documentIds. A call that names nothing beyond the deterministic homes still FILES, on those homes only, and says so — add pages later with route_record. ' +
         '⚠ A meeting or lecture TRANSCRIPT files with NOTES in `summary` (Theron, 2026-10-08): the gist, decisions, action items and dates, names spelled right. Without them the call is REFUSED; the transcript itself is kept on the record unchanged. ' +
         '⚠ ADR-0077: a GitHub commit or PR does not finish until every changed path has an answer. If a changed file\'s deepest folder (or, in a grab-bag folder like web/lib/engine/ or db/supabase/, the file itself) has no claim and no decline, the call is REFUSED with the open questions; answer each in folderDecisions and call again.',
       inputSchema: {
-        intakeItemId: z.string().describe('intake item uuid'),
+        intakeItemId: z.string().optional().describe('intake item uuid (required — intake_item_id is accepted too)'),
+        intake_item_id: z.string().optional().describe(INTAKE_ID_ALIAS_NOTE),
         intakeItemIds: z.array(z.string()).optional().describe(
           'MORE units to file exactly the same way, in one call — one record EACH, never merged (ADR-0076 §4.5). ' +
-          'For a conversation\'s waiting texts that you decided together: claim them all with `intake_claim`, then pass ' +
+          'Any units you hold a live claim on may be batched, even from separate intake_claim calls — except that texts from ' +
+          'DIFFERENT text conversations never share a batch. Claim them with `intake_claim`, then pass ' +
           'the first as intakeItemId and the rest here. title/summary/dedupeKey are ignored in a batch (each unit keeps its ' +
           'own), and a preview covers intakeItemId only. Each id is reported separately; a failure never hides behind a success.',
         ),
         orgId: z.string().describe('destination brain org uuid'),
-        documentIds: z.array(z.string()).optional().describe('additional pages in orgId — each a page `ref:` exactly as read_page shows it, or a brain_documents id (deterministic homes are merged automatically)'),
+        documentIds: z.array(z.string()).optional().describe('additional pages in orgId — each a page TITLE exactly as read_page shows it, its `ref:`, or a brain_documents id (deterministic homes are merged automatically). A title that matches no page, or more than one, is refused with the candidates listed'),
         title: z.string().optional(),
         summary: z.string().optional().describe(
           'what future retrieval reads first. For a meeting or lecture TRANSCRIPT these are its NOTES, and they are required: ' +
@@ -1317,7 +1332,7 @@ function renderNudge(payload) {
         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. ' +
+          'the page that should GOVERN this record (ADR-0062) — a page title, `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.',
         ),
@@ -1326,9 +1341,8 @@ function renderNudge(payload) {
         ),
         searchedForOtherHomes: z.boolean().optional().describe(
           'ADR-0051. "I looked for other homes and there are genuinely none." Only consulted when documentIds add no page ' +
-          'beyond the deterministic homes. ⚠ DO NOT SEND THIS ON THE FIRST CALL AS A MATTER OF COURSE — it is the answer AFTER ' +
-          'looking, not a way past the question. Measured 2026-09-25: 30 records filed through this verb in one afternoon with no ' +
-          'judged page on any of them.',
+          'beyond the deterministic homes; it suppresses the "filed on its deterministic homes only" note. Send it only AFTER ' +
+          'looking — it is the answer to the question, not a way past it.',
         ),
         folderDecisions: z.array(z.object({
           identifier: z.string().describe('the open question\'s identifier, or a folder above it that its answerWith lists'),
@@ -1356,6 +1370,9 @@ function renderNudge(payload) {
       },
     },
     async (args) => {
+      const unit = intakeIdFrom(args)
+      if (unit.error) return toolError(unit.error)
+      args = { ...args, intakeItemId: unit.id }
       // ADR-0076 §4.5 — A BATCH: one decision, N records. Theron, 2026-10-05: a conversation's waiting texts
       // are looked up once and handled together, but "it shouldn't file all of them as one record". The
       // loop lives here, as it does for place_staged_record's batch: the route stays one unit per call.
@@ -1380,8 +1397,8 @@ function renderNudge(payload) {
                 attachmentMeta: (args.documentIds ?? []).map(() => ({ origin: args.origin ?? 'llm' })),
                 ...(args.governingPage ? { governingDocumentId: args.governingPage } : {}),
                 ...(args.searchedForOtherHomes ? { searchedForOtherHomes: true } : {}),
-                // One placement is a decision about ONE conversation: the server refuses any id whose
-                // batch differs from the first id's, so a stray id is never filed onto these pages.
+                // The server refuses an id it cannot safely file with the first: a text from ANOTHER text
+                // conversation, or a unit this session holds no live claim on (not_same_batch).
                 sameBatchAs: batch[0],
                 ...obligationsFor(id),
               }),
@@ -1389,8 +1406,11 @@ function renderNudge(payload) {
             const o = await r.json().catch(() => null)
             const why = o?.error === 'obligations_unanswered'
               ? 'not filed — a text needs `obligations` ([] when it asks nothing)'
-              : (o?.error ?? `HTTP ${r.status}`)
-            results.push({ id, ok: r.ok, detail: r.ok ? `${o?.recordId ?? 'filed'}${filingObligationsBrief(o?.obligations)}` : why })
+              : o?.error === 'not_same_batch'
+                ? `not filed — ${o?.hint ?? 'not in the same batch as the first id'}`
+                : `${o?.error ?? `HTTP ${r.status}`}${o?.detail ? ` — ${o.detail}` : ''}`
+            const homesNote = o?.otherHomes?.note ? ' (deterministic homes only — add pages with route_record)' : ''
+            results.push({ id, ok: r.ok, detail: r.ok ? `${o?.recordId ?? 'filed'}${homesNote}${filingObligationsBrief(o?.obligations)}` : why })
           } catch (e) {
             results.push({ id, ok: false, detail: e.message })
           }
@@ -1484,6 +1504,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 = []
+      // ADR-0051, non-blocking since server 2026-10-22: filed, but on deterministic homes only.
+      if (body?.otherHomes?.note) lines.push(`⚠ ${body.otherHomes.note}`)
       const governingLine = renderGoverningLine(body?.governing)
       if (governingLine) lines.push(governingLine)
       const sa = body?.sessionAttachments
@@ -1538,11 +1560,16 @@ function renderNudge(payload) {
       description:
         'The OTHER terminal outcome for a claimed intake unit: this is nothing, drop it. Use it for content that should never become a record — unsubscribe receipts, empty greetings, marketing blasts, a stranger\'s photo — instead of materializing junk into a brain because materialize was the only verb available. IRREVERSIBLE: the ciphertext and nonces are destroyed in the same transaction, and a content-free tombstone stops the connector re-delivering the unit. You must already hold the claim (discarding something you never read is refused), `reason` is required and is stored, and it is one item per call — a loop discarding a whole pile on one decision is a bulk job, not judgment.',
       inputSchema: {
-        intakeItemId: z.string().describe('intake item uuid from intake_claim'),
+        intakeItemId: z.string().optional().describe('intake item uuid from intake_claim (required — intake_item_id is accepted too)'),
+        intake_item_id: z.string().optional().describe(INTAKE_ID_ALIAS_NOTE),
         reason: z.string().describe('why this is nothing — recorded on the claim, and the only surviving trace of the decision'),
       },
     },
-    async ({ intakeItemId, reason }) => {
+    async (args) => {
+      const { reason } = args
+      const unit = intakeIdFrom(args)
+      if (unit.error) return toolError(unit.error)
+      const intakeItemId = unit.id
       let res
       try {
         res = await fetchCortex(`${BASE}/api/intake/discard`, {
@@ -1577,12 +1604,17 @@ function renderNudge(payload) {
       description:
         'The THIRD terminal outcome, and the right one whenever the honest answer is "this is not mine to decide." Use it when a claimed unit is someone else\'s private content, when the destination brain is a real judgment call rather than a lookup, or when publishing and destroying are both wrong — a stranger\'s message thread, a photo you cannot place, an email whose brain depends on context only the owner has. Destroys NOTHING: the unit stays encrypted and intact, its state becomes `awaiting_user`, and your `question` is what the owner actually sees. Prefer this over letting a lease lapse — a lapsed lease says nothing, increments `attempts`, and hands the identical dead end to the next session. Requires the claim, one item per call.',
       inputSchema: {
-        intakeItemId: z.string().describe('intake item uuid from intake_claim'),
+        intakeItemId: z.string().optional().describe('intake item uuid from intake_claim (required — intake_item_id is accepted too)'),
+        intake_item_id: z.string().optional().describe(INTAKE_ID_ALIAS_NOTE),
         question: z.string().describe('what you need the owner to decide, in their words not yours — this is the entire message they get, so "which brain should this iMessage thread go to, if any?" beats "needs triage"'),
         options: z.array(z.string()).optional().describe('the concrete choices, when the decision is a pick rather than an open question — e.g. ["Personal","TTO","Discard — nothing to record"]. Stored on the question and rendered by intake_cleanup_status, so the owner can answer with a choice instead of prose.'),
       },
     },
-    async ({ intakeItemId, question, options }) => {
+    async (args) => {
+      const { question, options } = args
+      const unit = intakeIdFrom(args)
+      if (unit.error) return toolError(unit.error)
+      const intakeItemId = unit.id
       let res
       try {
         res = await fetchCortex(`${BASE}/api/intake/defer`, {
@@ -1617,11 +1649,16 @@ function renderNudge(payload) {
       description:
         'Give a claimed unit back to the queue WITHOUT deciding anything. This is not a fourth outcome — materialize, discard and defer resolve a unit; release just ends your hold on it. Use it when you claimed more than you can act on, or when the unit turns out to belong to work you are not doing. Prefer it over letting the lease expire: a lapse and a crash are indistinguishable in the ledger, so silently timing out costs the pile the one signal that says a session looked and chose to pass. Use intake_defer instead when the unit needs the OWNER to decide — release puts it back in front of the next session, which will hit whatever wall you did.',
       inputSchema: {
-        intakeItemId: z.string().describe('intake item uuid from intake_claim'),
+        intakeItemId: z.string().optional().describe('intake item uuid from intake_claim (required — intake_item_id is accepted too)'),
+        intake_item_id: z.string().optional().describe(INTAKE_ID_ALIAS_NOTE),
         reason: z.string().describe('why you are handing it back — "claimed too broadly", "not related to this session\'s work". Recorded on the claim, and the only thing distinguishing this from a lapsed lease'),
       },
     },
-    async ({ intakeItemId, reason }) => {
+    async (args) => {
+      const { reason } = args
+      const unit = intakeIdFrom(args)
+      if (unit.error) return toolError(unit.error)
+      const intakeItemId = unit.id
       let res
       try {
         res = await fetchCortex(`${BASE}/api/intake/release`, {
@@ -1715,11 +1752,12 @@ function renderNudge(payload) {
       description:
         'Read a PENDING intake unit\'s FULL decrypted body AND its `proposal` — the brain its signals point to, the pages it would attach to, the page that would govern it, the tier it would be born with, and `unclaimedIdentifiers` — without taking a lease. A read RECEIPT, not a claim (ADR-0035). The proposal rides with the look because they answer one question together: what is this, and where would it go — so you can tell whether a unit is yours to judge BEFORE leasing it. Use it when the settling feed\'s headline + candidate identifiers cannot tell you whether the unit belongs to your current work; looking is non-exclusive (any number of sessions may inspect the same unit) and always logged, so look freely rather than guessing from the headline — diligence is subsidized here. After looking: claim it if it is yours to process, or simply move on — no release needed, you never held it. The response includes how many sessions have looked (`looks`/`distinctLookers`): several looks and no claim is a sign the unit needs the triage agent or the owner, not another look. Resolved units are refused — read those as records.',
       inputSchema: {
-        intakeItemId: z.string().describe('intake item uuid, from the settling feed (intake_changes) or intake_claim'),
+        intakeItemId: z.string().optional().describe('intake item uuid, from the settling feed (intake_changes) or intake_claim (required — intake_item_id is accepted too)'),
+        intake_item_id: z.string().optional().describe(INTAKE_ID_ALIAS_NOTE),
         workingIdentifiers: z.array(z.string()).optional().describe('the identifiers your current work touches (repo:…, file:…, project:…) — stored on the receipt; feeds look→claim conversion analysis'),
       },
     },
-    async ({ intakeItemId, workingIdentifiers }) => renderIntakeLook(intakeItemId, workingIdentifiers ?? []),
+    async ({ intakeItemId, intake_item_id, workingIdentifiers }) => renderIntakeLook(requireIntakeId({ intakeItemId, intake_item_id }), workingIdentifiers ?? []),
   )
 
   server.registerTool(
@@ -4069,10 +4107,24 @@ function renderNudge(payload) {
         // a session had judged irrelevant was re-offered on every tool call — pilot B's 22-hour
         // re-offer defect (§11), recreated by the fix for the other half of the same problem.
         intake_item_id: z.string().optional().describe('the ARRIVAL id from the ⚡ ARRIVALS SETTLING block (not a record id)'),
+        // 2026-10-22: every other intake verb spells it intakeItemId; one session made 607 failing calls
+        // guessing between the two. Both are accepted — see intake_id_alias.mjs.
+        intakeItemId: z.string().optional().describe('same as intake_item_id — either spelling is accepted'),
+        recordId: z.string().optional().describe('same as record_id — either spelling is accepted'),
         reason: z.string().describe('WHY it is not yours — recorded, and the only thing that can later answer "why did nobody take this"'),
       },
     },
-    async ({ record_id, intake_item_id, reason }) => {
+    async (args) => {
+      const { reason } = args
+      const unit = intakeIdFrom(args, { required: false })
+      if (unit.error) return toolError(unit.error)
+      const intake_item_id = unit.id
+      const recCamel = typeof args.recordId === 'string' ? args.recordId.trim() : ''
+      const recSnake = typeof args.record_id === 'string' ? args.record_id.trim() : ''
+      if (recCamel && recSnake && recCamel !== recSnake) {
+        return toolError(`recordId (${recCamel}) and record_id (${recSnake}) disagree — pass one of them.`)
+      }
+      const record_id = recCamel || recSnake || null
       // ⚠ REFUSE BOTH AND NEITHER EXPLICITLY. Tonight's other defect was a parameter accepted by the
       // caller, dropped by the schema, and replaced by a default that did something else entirely.
       // An ambiguous decline must fail loudly, never pick one.

package/package.json

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