@theronap/agnoclast-mcp 0.9.177 → 0.9.178

package/lib/arrivals_notice.mjs

@@ -67,18 +67,26 @@ export function formatNotice(signals) {
   }
   if (offers.length) {
     lines.push(`⚡ ${total} arrival${total === 1 ? '' : 's'} asking THIS session to decide:`)
-    for (const o of offers.slice(0, 6)) {
-      // via_reason is carried through verbatim rather than flattened to "matched": an agent — or a
-      // person — who learns the stated reason is unreliable stops reading the reason at all.
-      const why = o.via_reason === 'matched'
-        ? 'matches your work'
-        : o.via_reason === 'declined'
-          ? 'every other matching session declined it'
-          : 'nothing matched it anywhere'
-      lines.push(`   · ${o.source} · ${o.hoursAgo}h ago — ${why}`)
-      lines.push(`     ${o.intakeItemId}`)
+    // ⚠ EVERY OFFER, GROUPED BY CASCADE STAGE — changed 2026-09-25 from the first SIX.
+    //
+    // Six of a deterministically-ordered twelve showed the SAME handful every turn while the rest of
+    // the pile stayed unreachable, and a session cannot claim what it is never shown. via_reason is
+    // still carried through verbatim rather than flattened — a reader who learns the stated reason is
+    // unreliable stops reading it — but it is printed ONCE PER GROUP instead of on every row, which
+    // is what makes listing all of them fit at all.
+    const STAGES = [
+      ['matched', 'matches your work'],
+      ['orphan', 'nothing matched them anywhere'],
+      ['declined', 'every other matching session declined them'],
+    ]
+    for (const [key, why] of STAGES) {
+      const group = offers.filter((o) => o.via_reason === key)
+      if (!group.length) continue
+      lines.push(`   ${why} (${group.length}):`)
+      for (const o of group) lines.push(`     ${o.intakeItemId}  ${o.source} · ${o.hoursAgo}h`)
     }
-    if (total > offers.length) lines.push(`   … and ${total - offers.length} more`)
+    // Only when the pile genuinely exceeds the server's scan window; `total` is counted before it.
+    if (total > offers.length) lines.push(`   … and ${total - offers.length} beyond the scan window`)
     lines.push('   (Claim + route them, or say they are not yours — they stay unclaimed until someone decides.)')
   }
   return lines.join('\n')

package/lib/server.mjs

@@ -1428,6 +1428,197 @@ function renderNudge(payload) {
     },
   )
 
+  // ── GMAIL WRITES — V5 / W5 of the Google write-scopes plan ───────────────────────────────────────
+  //
+  // Three tools over the W3 engine and its routes: change labels, save a reply draft, ask to send.
+  // Modelled on search_spam_email and send_imessage, as W5 specifies, and they inherit that pair's two
+  // habits — the 409 "which mailbox?" answer, and saying plainly what was NOT done.
+  //
+  // ⚠ THE OWNER CHECK IS THE SERVER'S, NOT OURS (review D14). Every route resolves the mailbox through
+  // loadOwnerGmailConnectors + canAccessMailbox, so being able to READ an email record in a shared brain
+  // never authorizes a write to it. These tools add no authorization of their own and must not imply any.
+  //
+  // ⚠ DARK UNTIL GOOGLE APPROVES THE WRITE SCOPES. In production GOOGLE_WRITE_SCOPES_LIVE is unset and
+  // every Gmail connector is read-only, so these return the auth/upgrade path. That is correct behaviour,
+  // not something to route around — they ship now so they are ready the day the scopes land.
+  //
+  // ⚠ NEVER SAY "NOTHING CHANGED" ON A FAILURE. modifyMessages chunks by BATCH_LIMIT and loops, and a
+  // throw in a later chunk discards the results already collected — so a 5xx can follow real changes. V4
+  // fixed exactly this lie in the web UI; the wording below is what keeps it fixed here.
+
+  /** ONE place a Gmail write failure becomes agent-readable text, so three tools cannot drift on it. */
+  const gmailWriteError = (res, body, tool) => {
+    const msg = typeof body?.error === 'string' ? body.error : null
+    if (res.status === 409 && Array.isArray(body?.accounts) && body.accounts.length) {
+      return toolError(`More than one connected Gmail account. Call ${tool} again with account: ${body.accounts.join(', ')}`)
+    }
+    if (res.status === 401 || res.status === 403) {
+      return toolError(
+        `${msg ?? 'Gmail refused that write.'} Gmail write access may not be granted on this account yet — ` +
+        `the person can check Connectors in Agnoclast. Nothing was changed.`)
+    }
+    if (res.status >= 500) {
+      return toolError(
+        `${msg ?? `Agnoclast could not finish that (${res.status}).`} ⚠ Part of it MAY already have happened. ` +
+        `Do not call ${tool} again — ask the person to check their mailbox first.`)
+    }
+    return toolError(msg ?? `${tool} failed (${res.status}).`)
+  }
+
+  server.registerTool(
+    'gmail_modify',
+    {
+      title: 'Change labels on the user\'s own Gmail messages',
+      description:
+        'Mark read or unread, archive, move back to the inbox, or add/remove a label on messages in the USER\'S OWN connected Gmail. Only the mailbox owner can act on a message — being able to read an email record in a shared brain does NOT authorize changing it, and the server enforces that. Identify messages with recordIds (Agnoclast email record ids) or messageIds (Gmail ids); they must all be in ONE mailbox. For add_label/remove_label pass labelId — one of the user\'s own labels (Label_…), or STARRED or IMPORTANT; call without labelId to get the list. THIS CHANGES THE USER\'S MAILBOX: confirm what they want before calling unless they just asked for it plainly. move_to_inbox is the undo for archive.',
+      inputSchema: {
+        action: z.enum(['mark_read', 'mark_unread', 'archive', 'move_to_inbox', 'add_label', 'remove_label'])
+          .describe('what to do to every message named; move_to_inbox undoes archive'),
+        recordIds: z.array(z.string()).optional().describe('Agnoclast email record ids, all in the same mailbox'),
+        messageIds: z.array(z.string()).optional().describe('Gmail message ids, all in the same mailbox — an alternative to recordIds'),
+        labelId: z.string().optional().describe('required for add_label / remove_label: one of the user\'s own labels (Label_…), or STARRED or IMPORTANT. Omit to be shown the available labels.'),
+        account: z.string().email().optional().describe('which connected Gmail account, when the user has more than one'),
+      },
+    },
+    async ({ action, recordIds, messageIds, labelId, account }) => {
+      if (!recordIds?.length && !messageIds?.length) {
+        return toolError('Name the messages to change: recordIds (Agnoclast email records) or messageIds (Gmail ids).')
+      }
+      // A label action with no id is not an error worth bouncing — answer it with the list, so the agent
+      // can act on the reply instead of guessing an id or asking the person for one.
+      if ((action === 'add_label' || action === 'remove_label') && !labelId) {
+        const lr = await fetchCortex(`${BASE}/api/gmail/labels${account ? `?account=${encodeURIComponent(account)}` : ''}`,
+          { headers: { Authorization: `Bearer ${TOKEN}` } })
+        const lb = await lr.json().catch(() => null)
+        if (!lr.ok) return gmailWriteError(lr, lb, 'gmail_modify')
+        const labels = Array.isArray(lb?.labels) ? lb.labels : []
+        if (!labels.length) return toolError(`${lb?.account ?? 'That mailbox'} has no labels you can add or remove. Nothing was changed.`)
+        return toolError(
+          `labelId is required for ${action}. Labels in ${lb.account}:\n` +
+          labels.map((l) => `- ${l.name} → ${l.id}${l.type === 'system' ? ' (system)' : ''}`).join('\n') +
+          `\nCall gmail_modify again with one of those ids. Nothing was changed.`)
+      }
+      const res = await fetchCortex(`${BASE}/api/gmail/messages/modify`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          action,
+          ...(labelId ? { labelId } : {}),
+          ...(account ? { account } : {}),
+          ...(recordIds?.length ? { recordIds } : { messageIds }),
+        }),
+      })
+      const body = await res.json().catch(() => null)
+      if (!res.ok) return gmailWriteError(res, body, 'gmail_modify')
+      // Per-message results, because a batch can partly fail and the person needs to know which.
+      const results = Array.isArray(body?.results) ? body.results : []
+      const failed = results.filter((r) => r && r.ok === false)
+      const changed = results.length - failed.length
+      const lines = [`${action} in ${body.account}: ${changed} of ${results.length} message${results.length === 1 ? '' : 's'} changed.`]
+      if (failed.length) {
+        lines.push(`⚠ ${failed.length} did NOT change:`)
+        for (const f of failed.slice(0, 10)) lines.push(`- ${f.id}: ${f.error ?? 'unknown error'}`)
+        if (failed.length > 10) lines.push(`- …and ${failed.length - 10} more`)
+      }
+      return { content: [{ type: 'text', text: lines.join('\n') }] }
+    },
+  )
+
+  server.registerTool(
+    'draft_email_reply',
+    {
+      title: 'Save a reply as a draft in the user\'s Gmail',
+      description:
+        'Write a reply to one of the USER\'S OWN emails and save it as a DRAFT in their Gmail, threaded under the original. NOTHING IS SENT — the user reviews and sends it themselves from Gmail, so this is the safe way to help with a reply. Identify the email by recordId (an Agnoclast email record) or messageId (a Gmail id). Only the mailbox owner can draft against a message; the server enforces that. Use request_send_email instead when the user wants it actually sent.',
+      inputSchema: {
+        recordId: z.string().optional().describe('the Agnoclast email record to reply to'),
+        messageId: z.string().optional().describe('the Gmail message id to reply to — an alternative to recordId'),
+        text: z.string().min(1).describe('the reply body, as plain text'),
+        account: z.string().email().optional().describe('which connected Gmail account, when the user has more than one'),
+      },
+    },
+    async ({ recordId, messageId, text, account }) => {
+      if (!recordId && !messageId) return toolError('Name the email to reply to: recordId or messageId.')
+      const res = await fetchCortex(`${BASE}/api/gmail/drafts`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ...(recordId ? { recordId } : { messageId }), text, ...(account ? { account } : {}) }),
+      })
+      const body = await res.json().catch(() => null)
+      if (!res.ok) return gmailWriteError(res, body, 'draft_email_reply')
+      return { content: [{ type: 'text', text:
+        `Draft saved in ${body.account} — NOT sent. The user reviews and sends it from Gmail: ${body.openUrl}` }] }
+    },
+  )
+
+  // request_send_email — the one tool here that can put mail in front of a person's contacts.
+  //
+  // ⚠ D5: THIS POST IS NOT IDEMPOTENT AND MUST NEVER BE RETRIED. `idempotent: false` is passed
+  // EXPLICITLY rather than relying on fetchCortex's GET/HEAD-only default, so that widening the default
+  // later cannot silently make sending an email retriable. A 5xx here may mean the mail went out.
+  //
+  // ⚠ THE reviewUrl CONTRACT (the V5 hand-off documented in send-requests/route.ts). The route OMITS the
+  // key when there is nothing to approve, so PRESENCE is the signal and `in` must not be used. Present →
+  // pending, and the sentence below is relayed verbatim. ABSENT → the send rule allowed it and the mail
+  // has ALREADY GONE; never invent a link or claim an approval is pending in that case.
+  server.registerTool(
+    'request_send_email',
+    {
+      title: 'Ask to send an email from the user\'s Gmail',
+      description:
+        'Send an email from the USER\'S OWN connected Gmail. By default this does NOT send immediately: it creates a request that WAITS for the user to approve it in Agnoclast, and it goes out at once only if their own send rule allows it. The message is frozen when the request is made, so write the final wording. Always show the user what you are about to send and get their agreement first. Returns either an approval link to relay to them, or confirmation that it already went. ⚠ NEVER call this twice for the same email — it is not idempotent, and a retry can send twice.',
+      inputSchema: {
+        to: z.array(z.string()).min(1).describe('recipient email addresses'),
+        subject: z.string().min(1).describe('the subject line'),
+        text: z.string().min(1).describe('the message body, as plain text'),
+        cc: z.array(z.string()).optional().describe('cc addresses'),
+        bcc: z.array(z.string()).optional().describe('bcc addresses'),
+        replyToRecordId: z.string().optional().describe('reply in the thread of this Agnoclast email record'),
+        replyToMessageId: z.string().optional().describe('reply in the thread of this Gmail message id'),
+        account: z.string().email().optional().describe('which connected Gmail account to send from, when the user has more than one'),
+      },
+    },
+    async ({ to, subject, text, cc, bcc, replyToRecordId, replyToMessageId, account }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/gmail/send-requests`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            to, subject, text,
+            ...(cc?.length ? { cc } : {}), ...(bcc?.length ? { bcc } : {}),
+            ...(replyToRecordId ? { replyToRecordId } : {}),
+            ...(replyToMessageId ? { replyToMessageId } : {}),
+            ...(account ? { account } : {}),
+          }),
+        }, { idempotent: false, retries: 0 })
+      } catch (e) {
+        // No response at all: the request may still have reached the server. Say so and stop.
+        return toolError(
+          `Could not confirm the send request: ${e.message} ⚠ It may have been created anyway. ` +
+          `Do NOT call request_send_email again — ask the user to check Email in Agnoclast.`)
+      }
+      const body = await res.json().catch(() => null)
+      if (!res.ok) return gmailWriteError(res, body, 'request_send_email')
+
+      // PRESENCE, not `in` — the route omits the key rather than sending null (pinned by
+      // src/send_request_verbs_test.ts). Absent means it already sent.
+      const reviewUrl = body?.reviewUrl
+      const acct = body?.request?.account ?? 'your Gmail'
+      const n = body?.request?.recipientCount ?? to.length
+      if (reviewUrl) {
+        // Relayed VERBATIM — this exact sentence is the contract the create route records.
+        return { content: [{ type: 'text', text:
+          `Send request created from ${acct} to ${n} recipient${n === 1 ? '' : 's'}. It is NOT sent yet. ` +
+          `Tell the user, in these words: It's waiting for your OK: ${reviewUrl}` }] }
+      }
+      const state = body?.request?.state ?? 'sent'
+      return { content: [{ type: 'text', text:
+        `Sent from ${acct} to ${n} recipient${n === 1 ? '' : 's'} — the user's send rule allowed it, so there is ` +
+        `nothing to approve (state: ${state}). Do not offer an approval link; the email has already gone.` }] }
+    },
+  )
+
   server.registerTool(
     'grep',
     {

package/package.json

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