@theronap/agnoclast-mcp 0.9.169 → 0.9.171

package/lib/server.mjs

@@ -1116,6 +1116,11 @@ function renderNudge(payload) {
         if (preview && res.status === 404) {
           return toolError('This server cannot preview a materialization yet — nothing was written. Materialize without mode, or wait for the server to update.')
         }
+        // Same redirect-not-dispatch rule as place_staged_record. A staged arrival needs no claim and
+        // no unseal, so the fix is a different verb rather than a retry of this one.
+        if (res.status === 404 && (await pileHolding(intakeItemId)) === 'staged') {
+          return toolError(`${intakeItemId} is a STAGED arrival, not an intake unit — \`intake_materialize\` cannot act on it. Use \`place_staged_record\` with the pages it belongs to; staged arrivals take no lease, so there is nothing to claim or release. (\`staged_look\` reads it first, and carries the brain-ladder proposal.)`)
+        }
         return toolError(body)
       }
       const body = await res.json()
@@ -1303,33 +1308,13 @@ function renderNudge(payload) {
     {
       title: 'Read an intake unit without claiming it',
       description:
-        'Read a PENDING intake unit\'s FULL decrypted body without taking a lease — a read RECEIPT, not a claim (ADR-0035). 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.',
+        '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'),
         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 }) => {
-      let res
-      try {
-        res = await fetchCortex(`${BASE}/api/intake/look`, {
-          method: 'POST',
-          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ intakeItemId, workingIdentifiers: workingIdentifiers ?? [] }),
-        })
-      } catch (e) {
-        return toolError(`Could not look: ${e.message}`)
-      }
-      const out = await res.json().catch(() => null)
-      if (!res.ok) {
-        if (out?.error === 'not_lookable') {
-          return toolError(`Not lookable: the unit is ${out?.state ?? 'resolved'} — resolved units are read as records, not looks.`)
-        }
-        if (out?.error === 'not_found') return toolError('No such intake unit in your account.')
-        return toolError(`Could not look: ${out?.error ?? res.status}${out?.detail ? ` — ${out.detail}` : ''}`)
-      }
-      return { content: [{ type: 'text', text: withAskNotice(JSON.stringify(out, null, 2)) }] }
-    },
+    async ({ intakeItemId, workingIdentifiers }) => renderIntakeLook(intakeItemId, workingIdentifiers ?? []),
   )
 
   server.registerTool(
@@ -2180,7 +2165,24 @@ function renderNudge(payload) {
         // managed to list these rows for weeks without making one of them actionable.
         lines.push(`  ${a.stagedId}`)
         lines.push(`    ${a.title ?? '(no subject)'}  ·  ${a.sourceType}  ·  ${a.occurredAt?.slice(0, 10) ?? ''}`)
-        if (a.blockingIdentifiers?.length) {
+        // 🔴 A QUESTION IS ALREADY OUT — say so FIRST, before any "held because" reason.
+        //
+        // Caught by using the feature once on real data, 2026-09-24, minutes after shipping it:
+        // `staged_defer` wrote the question, `intake_cleanup_status` showed it to the owner, and
+        // this listing rendered the arrival IDENTICALLY to three nobody had ever looked at. So the
+        // next session would judge it from scratch and hit the same wall — which is the exact
+        // failure the defer verb was built to end.
+        //
+        // ⚠ AND IT WAS IN THE API RESPONSE THE WHOLE TIME. `listStagedArrivals` returns
+        // `deferredQuestion`, with an engine test asserting it. The test passed. What was missing
+        // was a reader — the eighth instance of that shape this week, written into the very change
+        // whose stated purpose was avoiding it. An engine-level test cannot catch it, because the
+        // engine is not the surface anyone reads.
+        if (a.deferredQuestion) {
+          const asked = String(a.deferredQuestion.askedAt ?? '').slice(0, 10)
+          lines.push(`    ⏸ ASKED THE OWNER${asked ? ` on ${asked}` : ''} — do not re-judge this one: "${a.deferredQuestion.prompt}"`)
+          lines.push('       Still pending on purpose: it needs placing once they answer. Their answer is in `intake_cleanup_status.openQuestions`.')
+        } else if (a.blockingIdentifiers?.length) {
           lines.push(`    blocked by: ${a.blockingIdentifiers.join(', ')}`)
         } else {
           lines.push('    held because no brain could be determined (no unknown identifiers)')
@@ -2216,7 +2218,52 @@ function renderNudge(payload) {
         stagedId: z.string().describe('staged arrival id, from `staged_records` or the session-start arrivals block'),
       },
     },
-    async ({ stagedId }) => {
+    async ({ stagedId }) => renderStagedLook(stagedId),
+  )
+
+  // ⭐ ONE LOOK VERB, WHICHEVER PILE THE ID CAME FROM (ADR-0066 §1, the interface half).
+  //
+  // The two arrival piles are different tables with different keys, different sealing and different
+  // state models — collapsing the STORAGE is not on the table. What was actually costing decisions
+  // is that an agent holding an id could not tell which pile it came from, and the wrong verb
+  // answered "No such intake unit in your account." — a valid id, a real pending arrival, and an
+  // error that reads as "this does not exist". This file already records the same confusion from the
+  // other direction: "`intake_changes` returns ids from a different queue that `place` rejects.
+  // Twice in twelve hours a staged arrival could only be placed because a human read an id off a
+  // screen and pasted it."
+  //
+  // ⚠ READS DISPATCH, WRITES REDIRECT. Looking is free, non-exclusive and side-effect-free in both
+  // piles, so resolving the id and answering the question the caller actually asked is pure gain.
+  // The write verbs deliberately do NOT dispatch: `place_staged_record` and `intake_materialize`
+  // have different semantics (one replays a body through ingest, one unseals and publishes), so
+  // silently running the other one would be a different action than the caller requested. They name
+  // the right verb and stop.
+  function otherPileHint(id, pile) {
+    return pile === 'staged'
+      ? `That id is a STAGED arrival, not an intake unit. Staged verbs: \`staged_look\`, \`place_staged_record\`, \`discard_staged\`.`
+      : `That id is an INTAKE unit, not a staged arrival. Intake verbs: \`intake_look\`, \`intake_claim\`, \`intake_materialize\`, \`intake_discard\`, \`intake_defer\`.`
+  }
+
+  /** Does the OTHER pile hold this id? Only ever asked after the named pile said not-found. */
+  async function pileHolding(id) {
+    try {
+      const r = await fetchCortex(`${BASE}/api/staged/look?stagedId=${encodeURIComponent(id)}`, {
+        headers: { Authorization: `Bearer ${TOKEN}` },
+      })
+      if (r.ok) return 'staged'
+    } catch { /* fall through — a probe must never fail the caller's own verb */ }
+    try {
+      const r = await fetchCortex(`${BASE}/api/intake/look`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ intakeItemId: id, workingIdentifiers: [] }),
+      })
+      if (r.ok) return 'intake'
+    } catch { /* same */ }
+    return null
+  }
+
+  async function renderStagedLook(stagedId, { crossedFrom = null } = {}) {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/staged/look?stagedId=${encodeURIComponent(stagedId)}`, {
@@ -2227,6 +2274,9 @@ function renderNudge(payload) {
       }
       const out = await res.json().catch(() => null)
       if (res.status === 404) {
+        if (!crossedFrom && (await pileHolding(stagedId)) === 'intake') {
+          return renderIntakeLook(stagedId, [], { crossedFrom: 'staged' })
+        }
         return toolError(`No staged arrival ${stagedId} of yours. Staged rows are per-person and in no brain, so this means it is not yours or does not exist — the two are deliberately indistinguishable.`)
       }
       if (!res.ok) return toolError(`Could not read staged arrival ${stagedId}: ${out?.error ?? res.status}`)
@@ -2270,9 +2320,97 @@ function renderNudge(payload) {
             (l.summary ? `\n  summary  ${l.summary}\n` : '') +
             held +
             ladder +
+            (crossedFrom ? `\n\nℹ Resolved by id: you asked with an intake verb and this id is a STAGED arrival, so the staged look is above. ${otherPileHint(stagedId, 'staged')}` : '') +
             `\n⚠ This is the ENVELOPE. The message body was never stored (bodyStored: ${l.bodyStored === true}), so you have seen who sent it and what it was called — not what it says. Judge accordingly, and do not report having read it.`,
         }],
       }
+  }
+
+  async function renderIntakeLook(intakeItemId, workingIdentifiers = [], { crossedFrom = null } = {}) {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/intake/look`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ intakeItemId, workingIdentifiers: workingIdentifiers ?? [] }),
+        })
+      } catch (e) {
+        return toolError(`Could not look: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        if (out?.error === 'not_lookable') {
+          return toolError(`Not lookable: the unit is ${out?.state ?? 'resolved'} — resolved units are read as records, not looks.`)
+        }
+        if (out?.error === 'not_found') {
+          // ⚠ ONE HOP ONLY — `crossedFrom` stops the two renderers bouncing an id nobody holds back
+          // and forth. A genuinely unknown id must cost two probes and then stop.
+          if (!crossedFrom && (await pileHolding(intakeItemId)) === 'staged') {
+            return renderStagedLook(intakeItemId, { crossedFrom: 'intake' })
+          }
+          return toolError('No such intake unit in your account, and no staged arrival of yours has that id either — so it is not yours, or it does not exist.')
+        }
+        return toolError(`Could not look: ${out?.error ?? res.status}${out?.detail ? ` — ${out.detail}` : ''}`)
+      }
+      const note = crossedFrom
+        ? `ℹ Resolved by id: you asked with a staged verb and this id is an INTAKE unit, so the intake look is below. ${otherPileHint(intakeItemId, 'intake')}\n\n`
+        : ''
+      return { content: [{ type: 'text', text: withAskNotice(note + JSON.stringify(out, null, 2)) }] }
+  }
+
+  // ⭐ THE THIRD UNIFORM AFFORDANCE (ADR-0066 §1). Intake has had `intake_defer` since ADR-0062;
+  // staged had nothing, so an agent that correctly judged "this is not mine to decide" could only
+  // walk away — and the queue could not tell that apart from "nobody has looked yet", which wants
+  // the opposite response from the next reader.
+  server.registerTool(
+    'staged_defer',
+    {
+      title: 'Hand an owner-only decision about a staged arrival upward',
+      description:
+        'Record a question about a staged arrival that only its OWNER can answer, instead of leaving the arrival untouched. The staged twin of `intake_defer`. Use it when you have looked (`staged_look`) and the blocker is a decision rather than a lookup: which brain a message belongs to when several defensibly claim it (RUNG 4 says explicitly "do not pick"), or whether something is worth keeping at all. ' +
+        '⚠ NOT A DISCARD AND NOT A PLACEMENT — nothing about the arrival changes. It stays `pending` and keeps its body; the question is what is new, and it lands in `intake_cleanup_status.openQuestions` where the owner answers it. So this is the SAFEST verb in the staged surface, and the right one whenever the alternative is guessing. ' +
+        '⚠ ONE OPEN QUESTION PER ARRIVAL: deferring one that already has an open question returns that question rather than stacking a second. Two sessions hitting the same wall is evidence, not two questions. ' +
+        'A question is REQUIRED — a deferral with no question marks the arrival as handled while telling the owner nothing, which is the walking-away this verb exists to replace.',
+      inputSchema: {
+        stagedId: z.string().describe('staged arrival id, from `staged_records`, `staged_look` or the session-start arrivals block'),
+        question: z.string().describe('what the owner needs to decide, in their terms — name the arrival and the actual fork, e.g. "Elder Walker conference email — Personal or Known By Name? Both brains have pages that could claim it."'),
+        options: z.array(z.string()).optional().describe('the concrete choices when the decision is a pick rather than an open question — e.g. ["Personal","Known By Name","Discard — nothing to record"]. Rendered with the question, so the owner can answer with a choice instead of prose.'),
+      },
+    },
+    async ({ stagedId, question, options }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/staged/defer`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ stagedId, question, options }),
+        })
+      } catch (e) {
+        return toolError(`Could not defer: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        if (res.status === 404) {
+          // Same cross-pile courtesy the look verbs give (#1175): an intake id here is the wrong
+          // verb, not a missing arrival.
+          if ((await pileHolding(stagedId)) === 'intake') {
+            return toolError(`${stagedId} is an INTAKE unit, not a staged arrival — use \`intake_defer\` (it needs a claim first, unlike this verb).`)
+          }
+          return toolError(`No staged arrival ${stagedId} of yours. Staged rows are per-person, so this means it is not yours or does not exist.`)
+        }
+        if (out?.error === 'not_pending') {
+          return toolError(`That arrival is already ${out?.detail ?? 'resolved'} — there is nothing left for the owner to decide. Deferring a placed or discarded arrival would queue a question about a decision already made.`)
+        }
+        return toolError(`Could not defer: ${out?.error ?? res.status}${out?.detail ? ` — ${out.detail}` : ''}`)
+      }
+      return {
+        content: [{
+          type: 'text',
+          text: out?.alreadyOpen
+            ? `That arrival already had an open question (${out.questionId}) — returned rather than stacked a second. The owner sees it in \`intake_cleanup_status.openQuestions\`; it has not been asked twice.`
+            : `Deferred to the owner. The arrival is untouched and still pending; question ${out?.questionId} is queued in \`intake_cleanup_status.openQuestions\`. Nothing was placed or discarded.`,
+        }],
+      }
     },
   )
 
@@ -2971,6 +3109,13 @@ function renderNudge(payload) {
       const out = await res.json().catch(() => null)
       if (!res.ok && res.status !== 207) {
         const detail = out?.detail ? `\n${out.detail}` : ''
+        // ⚠ WRITES REDIRECT, THEY DO NOT DISPATCH. `place_staged_record` replays a stored body
+        // through ingest; `intake_materialize` unseals and publishes. Running one because the caller
+        // named the other would be a different action than they asked for — so name the verb and
+        // stop. The look verbs dispatch instead, because looking is free and side-effect-free.
+        if (res.status === 404 && ids.length === 1 && (await pileHolding(staged_id)) === 'intake') {
+          return toolError(`${staged_id} is an INTAKE unit, not a staged arrival — \`place_staged_record\` cannot act on it. Claim it with \`intake_claim {intakeItemIds: ["${staged_id}"]}\` and then \`intake_materialize\`. (\`intake_look\` reads it first, free and without a lease.)`)
+        }
         return toolError(`Could not place ${staged_id}: ${out?.error ?? res.status}${detail}`)
       }
       // 207 and the no-record branch both mean the content LANDED and the attach did not. Report

package/package.json

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