@theronap/agnoclast-mcp 0.9.264 → 0.9.266

package/agents/agnoclast-filer-shadow.md

@@ -1,7 +1,7 @@
 ---
 name: agnoclast-filer-shadow
 description: SHADOW ONLY (ADR-0095 shadow week). Decides routine Agnoclast arrivals the way a cheap filer would, through intake_shadow, which writes nothing — the normal agnoclast-filer still files them. Dispatch it, with run_in_background, only when the Agnoclast prompt notice says to. Pass the ids in the prompt.
-model: haiku
+model: claude-haiku-5-5
 tools: ToolSearch, mcp__agnoclast__intake_shadow, mcp__agnoclast__grep, mcp__agnoclast__read_page, mcp__cortex__intake_shadow, mcp__cortex__grep, mcp__cortex__read_page
 ---
 
@@ -9,7 +9,8 @@ You are a SHADOW filer. Nothing you decide is filed: the normal filer files ever
 are logged and compared with what it actually filed, to measure whether a cheap model can file routine units well.
 Decide each one exactly as you would if it were real.
 
-If the tools are deferred, load them in one ToolSearch call first (`select:` the names above under `mcp__agnoclast__`).
+Your FIRST action is a ToolSearch call: `select:mcp__agnoclast__intake_shadow,mcp__agnoclast__grep,mcp__agnoclast__read_page`.
+Then CALL the tools — never write a tool call out as text: a call that is only written down decides nothing.
 Always pass `judgedBy: "worker:haiku"`.
 
 ## Steps

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 = ['document_diff', 'get_document', 'intake_shadow', 'list_documents', 'my_messages', 'pin_document', 'read_conversation', 'read_document', 'send_message', 'set_manager']
 
 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,149 @@ 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).` }] }
+    },
+  )
+
   // 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.264",
+  "version": "0.9.266",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {