@theronap/agnoclast-mcp 0.9.265 → 0.9.267

package/lib/release_gate.mjs

@@ -5,7 +5,7 @@
 // that web/lib/engine/release.test.ts pins to the server's registry.
 
 /** Tools any release flag gates — hidden when the server cannot be asked. Mirror of allGatedTools(). */
-export const GATED_FALLBACK = ['intake_shadow', 'my_messages', 'read_conversation', 'send_message', 'set_manager']
+export const GATED_FALLBACK = ['attach_document', 'document_diff', 'get_document', 'intake_shadow', 'list_documents', 'my_messages', 'pin_document', 'read_conversation', 'read_document', 'send_message', 'set_manager', 'upload_document_version']
 
 export const RELEASE_FETCH_TIMEOUT_MS = 2500
 

package/lib/server.mjs

@@ -2323,10 +2323,12 @@ function renderNudge(payload) {
           // everything attached to it.
           //
           // The honest condition is: nothing to show at all.
-          if (!t.identifiers?.length && !t.events?.length) {
+          if (!t.identifiers?.length && !t.events?.length && !t.headerNotes?.length) {
             return { content: [{ type: 'text', text: `"${name}" has no history yet — no identifier stamps and nothing attached. Stamp its page with [[repo:owner/name]] (what it identifies), or attach records to it, and events will accrue here.` }] }
           }
           const lines = [`# ${name} — node timeline (history; the page is the present)`]
+          // ADR-0096: pinned files head the timeline. Composed server-side (pageFileNotes), printed verbatim.
+          for (const n of t.headerNotes ?? []) lines.push(n)
           if (t.identifiers?.length) {
             lines.push(`Joins: ${t.identifiers.map((i) => `[[${i.id}]] · ${i.visibleCount} visible`).join('  |  ')}${t.incomplete ? '  (partial — one join failed to read)' : ''}`)
           } else {
@@ -7271,6 +7273,215 @@ function renderNudge(payload) {
     },
   )
 
+  // ── Stored documents (ADR-0096): files kept in Agnoclast on a page, versioned, readable as text ──
+  server.registerTool(
+    'pin_document',
+    {
+      title: 'Pin a stored file to the top of its page',
+      description: 'Pin (or unpin) a stored file so it heads its page and the page\'s timeline — for the file a page is really about, like the accounting workbook on an "Accounting records" page. Needs edit access to the page. Get file_id from the 📌/📎 lines read_page prints at the top of a page.',
+      inputSchema: {
+        file_id: z.string().describe('the stored file\'s id (read_page prints it as "id …")'),
+        pinned: z.boolean().optional().describe('false to unpin; default true'),
+      },
+    },
+    async ({ file_id, pinned }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/stored-files/${encodeURIComponent(file_id)}/pin`, {
+          method: 'POST', headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ pinned: pinned !== false }),
+        })
+      } catch (e) { return toolError(`Could not pin: ${e.message}`) }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return toolError(`Could not ${pinned === false ? 'unpin' : 'pin'}: ${out?.detail ?? out?.error ?? res.status}`)
+      const t = out.file?.title ?? file_id
+      if (!out.changed) return { content: [{ type: 'text', text: `"${t}" was already ${pinned === false ? 'unpinned' : 'pinned'}.` }] }
+      return { content: [{ type: 'text', text: pinned === false ? `Unpinned "${t}".` : `Pinned "${t}" — it now heads its page and the page's timeline.` }] }
+    },
+  )
+
+  const docFail = async (verb, res) => {
+    const out = await res.json().catch(() => null)
+    return toolError(`Could not ${verb}: ${out?.detail ?? out?.error ?? res.status}`)
+  }
+
+  server.registerTool(
+    'list_documents',
+    {
+      title: 'List the stored files on a page',
+      description: 'The files kept in Agnoclast on a page (a spreadsheet, a Word document, a CSV…), pinned first, with each one\'s id, current version and whether it can be read as text. read_page also names them at the top of the page. Then read_document to read one, document_diff to see what changed, get_document to download it.',
+      inputSchema: { page: z.string().describe('the page: its exact title, its `ref:` from read_page, or a document id') },
+    },
+    async ({ page }) => {
+      let res
+      try { res = await fetchCortex(`${BASE}/api/stored-files?${new URLSearchParams({ page })}`, { headers: { Authorization: `Bearer ${TOKEN}` } }) }
+      catch (e) { return toolError(`Could not list files: ${e.message}`) }
+      if (!res.ok) return docFail('list files', res)
+      const out = await res.json()
+      if (!out.files?.length) return { content: [{ type: 'text', text: `No stored files on "${out.page?.title ?? page}".` }] }
+      const lines = [`Stored files on "${out.page?.title ?? page}":`]
+      for (const f of out.files) {
+        const v = f.versions?.[0]
+        lines.push(`${f.pinned ? '📌' : '-'} "${f.title}" — id ${f.id} · v${f.latestVersion}${v ? ` · ${v.filename} · ${Math.round(v.sizeBytes / 1024)} KB · ${String(v.createdAt).slice(0, 10)}${v.readable === 'ok' ? '' : ' · not readable as text'}` : ''}`)
+      }
+      return { content: [{ type: 'text', text: lines.join('\n') }] }
+    },
+  )
+
+  server.registerTool(
+    'read_document',
+    {
+      title: 'Read a stored file as text',
+      description: 'Read a file kept in Agnoclast (Excel, Word, CSV, plain text) as text. A workbook reads as one table per sheet, then each formula with its value — a formula marked "⚠ not calculated" has no value yet (the file was saved without recalculating), which is NOT zero. Long files come in pages: pass the returned offset to continue. Pass `sheet` to read one sheet, `version` for an older version, format "cells" for one line per cell.',
+      inputSchema: {
+        file_id: z.string().describe('the stored file\'s id (from read_page\'s 📌/📎 lines or list_documents)'),
+        version: z.number().int().positive().optional().describe('a version number; default the latest'),
+        sheet: z.string().optional().describe('a workbook: read only this sheet'),
+        format: z.enum(['grid', 'cells']).optional().describe('a workbook: "grid" (default) or "cells" — one line per cell, Sheet!A1<TAB>value<TAB>=formula'),
+        offset: z.number().int().min(0).optional().describe('continue from here (the previous call says where)'),
+      },
+    },
+    async ({ file_id, version, sheet, format, offset }) => {
+      const q = new URLSearchParams()
+      if (version) q.set('version', String(version))
+      if (sheet) q.set('sheet', sheet)
+      if (format) q.set('format', format)
+      if (offset) q.set('offset', String(offset))
+      let res
+      try { res = await fetchCortex(`${BASE}/api/stored-files/${encodeURIComponent(file_id)}/text?${q}`, { headers: { Authorization: `Bearer ${TOKEN}` } }) }
+      catch (e) { return toolError(`Could not read the file: ${e.message}`) }
+      if (!res.ok) return docFail('read the file', res)
+      const o = await res.json()
+      const head = [`# ${o.title} — ${o.filename}, v${o.version}${o.version !== o.latestVersion ? ` (latest is v${o.latestVersion})` : ''}`]
+      if (o.sheets) head.push(`Sheets: ${o.sheets.map((n) => `"${n}"`).join(', ')}`)
+      if (o.note) head.push(o.note)
+      if (o.offset) head.push(`(continuing from character ${o.offset} of ${o.total})`)
+      const tail = o.nextOffset != null
+        ? `\n\n— ${o.total - o.nextOffset} more characters. Continue with read_document file_id:"${o.id}" offset:${o.nextOffset}${version ? ` version:${version}` : ''}${sheet ? ` sheet:"${sheet}"` : ''}.`
+        : ''
+      return { content: [{ type: 'text', text: `${head.join('\n')}\n\n${o.text}${tail}` }] }
+    },
+  )
+
+  server.registerTool(
+    'document_diff',
+    {
+      title: 'What changed in a stored file',
+      description: 'Compare two versions of a stored file — by default the latest against the one before. A workbook is compared cell by cell (`~ Invoices!D21: "1,200" → "1,450"`), a document paragraph by paragraph. The first line says how big the change is, so you can tell a small edit from a rewrite. Use it when read_page warns that a file changed after the page was written, then decide whether what the page says about the file is still true — and fix the page with edit_page if not.',
+      inputSchema: {
+        file_id: z.string().describe('the stored file\'s id'),
+        from: z.number().int().positive().optional().describe('older version; default the one before `to`'),
+        to: z.number().int().positive().optional().describe('newer version; default the latest'),
+      },
+    },
+    async ({ file_id, from, to }) => {
+      const q = new URLSearchParams()
+      if (from) q.set('from', String(from))
+      if (to) q.set('to', String(to))
+      let res
+      try { res = await fetchCortex(`${BASE}/api/stored-files/${encodeURIComponent(file_id)}/diff?${q}`, { headers: { Authorization: `Bearer ${TOKEN}` } }) }
+      catch (e) { return toolError(`Could not compare versions: ${e.message}`) }
+      if (!res.ok) return docFail('compare versions', res)
+      const o = await res.json()
+      const lines = [`# ${o.title}: v${o.from} (${String(o.fromDate).slice(0, 10)}) → v${o.to} (${String(o.toDate).slice(0, 10)})`, `${o.magnitude === 'large' ? 'LARGE change' : o.magnitude === 'small' ? 'Small change' : 'No change'}: ${o.summary}`]
+      if (o.lines?.length) lines.push('', ...o.lines)
+      if (o.truncated) lines.push(`… and ${o.truncated} more changes not shown.`)
+      return { content: [{ type: 'text', text: lines.join('\n') }] }
+    },
+  )
+
+  server.registerTool(
+    'get_document',
+    {
+      title: 'Download a stored file',
+      description: 'Download the original of a file kept in Agnoclast (the actual .xlsx/.docx/…) to ~/Downloads/cortex/ and return its local path — for when you need the real file, e.g. to open it with a spreadsheet library. To just read it, read_document is faster.',
+      inputSchema: {
+        file_id: z.string().describe('the stored file\'s id'),
+        version: z.number().int().positive().optional().describe('a version number; default the latest'),
+      },
+    },
+    async ({ file_id, version }) => {
+      let res
+      try { res = await fetchCortex(`${BASE}/api/stored-files/${encodeURIComponent(file_id)}/download${version ? `?version=${version}` : ''}`, { headers: { Authorization: `Bearer ${TOKEN}` } }) }
+      catch (e) { return toolError(`Could not download: ${e.message}`) }
+      if (!res.ok) return docFail('download', res)
+      const buf = Buffer.from(await res.arrayBuffer())
+      const m = /filename="([^"]+)"/.exec(res.headers.get('content-disposition') ?? '')
+      const name = (m ? m[1] : `agnoclast-file-${file_id}`).replace(/[^\w.\- ]/g, '_')
+      const dir = join(homedir(), 'Downloads', 'cortex')
+      mkdirSync(dir, { recursive: true })
+      const path = join(dir, name)
+      writeFileSync(path, buf)
+      return { content: [{ type: 'text', text: `Saved v${res.headers.get('x-stored-file-version') ?? '?'} of the stored file to ${path} (${buf.length} bytes).` }] }
+    },
+  )
+
+  // UPLOADS (slice 4). The server refuses an assistant unless the person turned on "Let assistants upload
+  // files" in Agnoclast → Settings — a switch only the console can flip. These tools never ask for it.
+  // Bytes go straight to storage on the signed URL the server hands out, then the server reads them back.
+  const uploadStored = async (target, path, extra = {}) => {
+    let st
+    try { st = statSync(path) } catch { return toolError(`No file at ${path}.`) }
+    if (!st.isFile()) return toolError(`${path} is not a file.`)
+    const filename = path.split(/[\\/]/).pop()
+    let res
+    try {
+      res = await fetchCortex(`${BASE}/api/stored-files/uploads`, {
+        method: 'POST', headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ...target, ...extra, filename, size: st.size }),
+      })
+    } catch (e) { return toolError(`Could not start the upload: ${e.message}`) }
+    const begin = await res.json().catch(() => null)
+    if (!res.ok) return toolError(`Not uploaded: ${begin?.detail ?? begin?.error ?? res.status}`)
+    let put
+    try {
+      put = await fetch(begin.signedUrl, { method: 'PUT', headers: { 'content-type': begin.contentType ?? 'application/octet-stream', 'x-upsert': 'false' }, body: readFileSync(path) })
+    } catch (e) { return toolError(`Not uploaded: storage could not be reached (${e.message}).`) }
+    if (!put.ok) return toolError(`Not uploaded: storage refused the file (${put.status}).`)
+    let commit
+    try {
+      commit = await fetchCortex(`${BASE}/api/stored-files/uploads/${begin.uploadId}/commit`, { method: 'POST', headers: { Authorization: `Bearer ${TOKEN}` } })
+    } catch (e) { return toolError(`Uploaded but not saved: ${e.message}`) }
+    const c = await commit.json().catch(() => null)
+    if (!commit.ok) return toolError(`Uploaded but not saved: ${c?.detail ?? c?.error ?? commit.status}`)
+    const lines = c.unchanged
+      ? [`"${c.title}" is byte-for-byte identical to its current version (v${c.version}); nothing was added.`]
+      : [`Saved "${c.title}" as version ${c.version} (id ${c.fileId}, ${Math.round(c.sizeBytes / 1024)} KB, sha256 ${c.byteSha256.slice(0, 12)}…)${c.pinned ? ', pinned to its page' : ''}.`]
+    if (!c.unchanged && c.contentUnchanged) lines.push('Its contents read the same as the previous version (only the bytes changed).')
+    if (c.extractStatus && c.extractStatus !== 'ok' && c.extractStatus !== 'unchanged') lines.push(`Not readable as text: ${c.extractNote ?? c.extractStatus}.`)
+    else if (c.extractNote) lines.push(c.extractNote)
+    if (!c.unchanged && c.version > 1 && !c.contentUnchanged) lines.push(`See what changed with document_diff file_id:"${c.fileId}", and update the page if what it says about the file is no longer true.`)
+    return { content: [{ type: 'text', text: lines.join('\n') }] }
+  }
+
+  server.registerTool(
+    'attach_document',
+    {
+      title: 'Store a file on a page',
+      description: 'Keep a local file (Excel, Word, CSV, PDF…) in Agnoclast on a page: it is versioned, readable with read_document, and visible to exactly who can read that page. Needs edit access to the page, and the person must have turned on "Let assistants upload files" in Agnoclast → Settings — if it is off this is refused; tell them, do not work around it. Up to 50 MB. Pass pin:true for the file the page is about.',
+      inputSchema: {
+        page: z.string().describe('the page it lives on: exact title, `ref:` or document id'),
+        path: z.string().describe('absolute path of the local file'),
+        title: z.string().optional().describe('a name for it; default the filename without its extension'),
+        pin: z.boolean().optional().describe('pin it to the top of the page and its timeline'),
+      },
+    },
+    async ({ page, path, title, pin }) => uploadStored({ page }, path, { ...(title ? { title } : {}), ...(pin ? { pin: true } : {}) }),
+  )
+
+  server.registerTool(
+    'upload_document_version',
+    {
+      title: 'Upload a new version of a stored file',
+      description: 'Upload a local file as the NEW VERSION of a file already stored in Agnoclast. Every earlier version is kept. Identical bytes add nothing. Same permission as attach_document: refused unless the person turned on "Let assistants upload files". Afterwards, check document_diff and update the page if it no longer describes the file.',
+      inputSchema: {
+        file_id: z.string().describe('the stored file\'s id'),
+        path: z.string().describe('absolute path of the local file'),
+      },
+    },
+    async ({ file_id, path }) => uploadStored({ fileId: file_id }, path),
+  )
+
   // send_imessage — ask to send a text from the user's own Mac (ADR-0076). It no longer texts from this
   // machine: it creates a request on Agnoclast that waits on /email → Waiting for the user's OK (or their
   // web send rule approves it), and the user's Mac — the desktop app, through Messages — sends it and

package/package.json

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