@theronap/agnoclast-mcp 0.9.185 → 0.9.187

package/lib/custom_sources.mjs

@@ -0,0 +1,167 @@
+// Custom sources, for an agent — the pure half of create_custom_source / list_custom_sources /
+// set_custom_source_home (server.mjs registers them). Turns tool arguments into the setup API's body and
+// its answers into text an agent can act on. No I/O here, so every rendering has a test.
+//
+// Why these tools exist (Theron, 2026-09-29): "would you have known how to fix the script to connect to
+// the custom connector if you didn't build the system in the first place? Because if not, real users
+// won't be able to make their custom connectors." The agent that wired the first real source needed
+// three things no tool gave it — the source's field mapping, the page it files onto, and a way to see
+// where its items landed. list_custom_sources and list_records page: are those; create_custom_source is
+// the setup itself, which he did not want a person doing alone.
+
+/** The home part of a setup/channel body, from tool arguments. undefined = let the server default it. */
+export function homeFromArgs(a, fallbackTitle) {
+  if (a.home_page) return { page: String(a.home_page).trim() }
+  const setAside = Array.isArray(a.not_any_of) ? a.not_any_of.map((x) => String(x).trim()).filter(Boolean) : []
+  const title = a.new_page_title ? String(a.new_page_title).trim() : ''
+  if (!title && !setAside.length && !a.new_page_brain) return undefined
+  return {
+    title: title || fallbackTitle,
+    ...(a.new_page_brain ? { brain: String(a.new_page_brain).trim() } : {}),
+    ...(a.description ? { description: String(a.description) } : {}),
+    ...(setAside.length ? { notAnyOf: setAside } : {}),
+    ...(a.reason ? { reason: String(a.reason) } : {}),
+  }
+}
+
+export function renderMapping(m) {
+  const roles = ['id', 'time', 'title', 'body', 'group', 'url']
+  const parts = roles.filter((r) => m?.[r]).map((r) => `${r} ← ${m[r]}`)
+  if (m?.people?.length) parts.push(`people ← ${m.people.join(', ')}`)
+  return parts.length ? parts.join(' · ') : '(none — every item is titled by the source name and identified by its content)'
+}
+
+function ago(iso, now) {
+  if (!iso) return 'never used'
+  const s = Math.max(0, (now - new Date(iso).getTime()) / 1000)
+  if (s < 90) return 'used just now'
+  if (s < 5400) return `used ${Math.round(s / 60)}m ago`
+  if (s < 129600) return `used ${Math.round(s / 3600)}h ago`
+  return `used ${Math.round(s / 86400)}d ago`
+}
+
+/** GET /api/custom-connectors → text. */
+export function formatSources(connectors, now = Date.now()) {
+  if (!connectors?.length) return 'You have no custom sources. create_custom_source sets one up.'
+  return connectors.map((c) => {
+    const where = c.disabledAt
+      ? `OFF since ${String(c.disabledAt).slice(0, 10)} — its key no longer works; everything it sent is kept`
+      : c.channel && !c.channel.homeRef
+        ? 'files onto a page you can no longer read (you left its brain, or its privacy changed) — point it elsewhere with set_custom_source_home'
+      : c.mode === 'channel' && c.channel
+        ? `files onto "${c.channel.homeTitle}" (${c.channel.brain}) — ref ${c.channel.homeRef}; read it with list_records page:"${c.channel.homeRef}" source:"custom"`
+        : c.channel
+          ? `waits in the pile to be sorted, suggested for "${c.channel.homeTitle}" (${c.channel.brain})`
+          : 'waits in the pile to be sorted onto the pages each item belongs to'
+    return [
+      `• ${c.name}  [id ${c.id}]  ${c.identifier} · ${c.shape} · ${c.purpose}`,
+      `  where: ${where}`,
+      `  mapping: ${renderMapping(c.mapping)}`,
+      `  key: ${c.key ? `${c.key.prefix}… · ${ago(c.key.lastUsedAt, now)}` : 'none live'}`,
+    ].join('\n')
+  }).join('\n')
+}
+
+/** The pages that may already be the home, as a numbered list an agent reads and then judges. */
+export function renderCandidates(cands) {
+  return (cands ?? []).map((c, i) => [
+    `  ${i + 1}. "${c.title}" — ${c.brain} · ${c.records} item${c.records === 1 ? '' : 's'} on it · ${c.why ?? (c.exact ? 'same name' : 'similar name')}`,
+    `     id: ${c.documentId}   ref: ${c.ref}`,
+    ...(c.snippet ? [`     “${c.snippet}”`] : []),
+  ].join('\n')).join('\n')
+}
+
+/** Why a home was refused, and exactly what to do next. */
+export function renderHomeProblem(p) {
+  if (!p) return ''
+  if (p.error === 'home_candidates' || p.error === 'reason_required') {
+    return [
+      p.error === 'reason_required'
+        ? 'A new page needs a `reason`: say why none of these pages is the home.'
+        : 'These existing pages may already be what this source is about — nothing was created:',
+      renderCandidates(p.candidates),
+      '',
+      'Read them (read_page ref:"…") and decide WITH the person. Then either:',
+      '  • file onto one: home_page:"<its id or ref>"  (preferred — one page per subject), or',
+      '  • make a new page: new_page_title:"…" + not_any_of:[every id above] + reason:"why none of them is the home".',
+    ].join('\n')
+  }
+  if (p.error === 'home_exists') {
+    return `${p.detail ?? 'A page with that name already exists.'}\n${renderCandidates(p.candidates)}\nFile onto it with home_page:"${p.documentId ?? '<its id>'}", or choose a genuinely different name.`
+  }
+  if (p.error === 'home_ambiguous') return `${p.detail}\n${renderCandidates(p.candidates)}\nPass one of these ids as home_page.`
+  if (p.error === 'brain_required' || p.error === 'brain_not_found' || p.error === 'brain_ambiguous') {
+    return `Say which brain the new page goes in — new_page_brain: one of ${(p.brains ?? []).map((b) => `"${b.brain}"`).join(', ')}.`
+  }
+  if (p.error === 'cannot_write_brain') return 'You cannot add to that brain right now (not an active member, or writing is paused).'
+  if (p.error === 'home_not_found') return 'No page you can read has that id or ref. Use an id from the candidate list, or a ref read_page printed.'
+  return `${p.error}${p.detail ? `: ${p.detail}` : ''}`
+}
+
+function renderPreview(pv, problem) {
+  if (problem) return `⚠ The sample would be REFUSED as mapped: ${problem}. Fix the mapping (or the sample) before wiring anything.`
+  if (!pv) return 'No sample given — pass one real item as `sample` to see how it arrives and to have the mapping filled in.'
+  return `The sample will arrive as: "${pv.title}" · ${pv.time ?? 'time: when it arrives'}${pv.id ? ` · id ${pv.id}` : ' · no id — identified by its content'}${pv.people?.length ? ` · people ${pv.people.join(', ')}` : ''}${pv.body ? `\n  main text: ${pv.body.length > 200 ? `${pv.body.slice(0, 199)}…` : pv.body}` : ' · (no main text mapped)'}`
+}
+
+/** POST /api/custom-connectors with dryRun → text. */
+export function formatDryRun(r) {
+  const home = r.mode === 'ingest'
+    ? 'Items would wait in the pile, to be sorted onto the pages each belongs to.'
+    : r.home
+      ? r.home.created
+        ? `Items would file onto a NEW page "${r.home.title}" in ${r.home.brain} — no existing page matched its name or description.`
+        : `Items would file onto the existing page "${r.home.title}" (${r.home.brain}) — ref ${r.home.ref}.`
+      : renderHomeProblem(r.homeProblem)
+  return [
+    'DRY RUN — nothing was created.',
+    `Mapping${r.mappingSuggested ? ' (suggested from your sample — check it)' : ''}: ${renderMapping(r.mapping)}`,
+    renderPreview(r.preview, r.sampleProblem),
+    '',
+    home,
+  ].join('\n')
+}
+
+/** POST /api/custom-connectors (created) → text. The key is in it exactly once. */
+export function formatCreated(r, keyFileHint) {
+  const c = r.connector
+  const home = r.channel
+    ? `Files onto ${r.channel.homeCreated ? 'a NEW page' : 'your existing page'} "${r.channel.homeTitle}" (${r.channel.brain}) — ref ${r.channel.homeRef}.`
+    : r.channelError
+      ? `⚠ Created, but NOT filing onto a page yet — ${renderHomeProblem(r.channelError)}\nFix it with set_custom_source_home; until then items wait in the pile.`
+      : 'Items wait in the pile, to be sorted onto the pages each belongs to.'
+  // The generated script embeds the key; an agent copies what it is shown into files, so show it reading
+  // the key from where it was told to store it instead.
+  const python = (r.snippets?.python ?? '').split(r.key).join('<YOUR KEY — read it from the key file or env var>')
+  return [
+    `Created custom source "${c.name}" — ${c.identifier} (id ${c.id}).`,
+    home,
+    '',
+    'KEY — shown ONCE, never again:',
+    `  ${r.key}`,
+    `Store it now, outside any repo: ${keyFileHint(c.slug)} (chmod 600), or an environment variable. Never commit it or paste it into a chat or a page. It can only ADD items to this one source; if it leaks, rotate it on the Data sources page.`,
+    '',
+    `Endpoint: POST ${r.endpoint}   Authorization: Bearer <key>   body: { "items": [ … ] } — up to 100 items per call, 64 KB each, 30 calls a minute.`,
+    `Mapping: ${renderMapping(r.mapping)}`,
+    renderPreview(r.preview, r.sampleProblem),
+    '',
+    'Python (read the key from where you stored it):',
+    python,
+    '',
+    'Next: send the real sample, then confirm it landed —',
+    r.channel ? `  list_records page:"${r.channel.homeRef}" source:"custom"` : '  list_records source:"custom"',
+    'Each item in the push response is filed / pending / duplicate (already received) / rejected (with the reason). Re-sending an unchanged item is safe; a changed one is kept as a new version.',
+  ].join('\n')
+}
+
+/** Find a source by id or name in a list_custom_sources answer. */
+export function pickSource(connectors, ref) {
+  const want = String(ref ?? '').trim().toLowerCase()
+  const live = (connectors ?? []).filter((c) => !c.disabledAt)
+  const byId = live.find((c) => c.id.toLowerCase() === want || c.identifier.toLowerCase() === want || c.slug?.toLowerCase() === want)
+  if (byId) return { ok: true, source: byId }
+  const byName = live.filter((c) => c.name.toLowerCase() === want)
+  if (byName.length === 1) return { ok: true, source: byName[0] }
+  if (byName.length > 1) return { ok: false, message: `${byName.length} sources are named "${ref}" — pass one's id:\n${formatSources(byName)}` }
+  return { ok: false, message: `No live custom source is called "${ref}". Yours:\n${formatSources(live)}` }
+}

package/lib/redact.mjs

@@ -10,6 +10,8 @@
 // [pattern, replacement]. Order matters: most specific Anthropic forms first so a
 // login token reads as [REDACTED:anthropic-oauth], not the generic key bucket.
 const PATTERNS = [
+  // Agnoclast's own write-only ingest keys (custom sources): agn_in_ + 43 base64url characters.
+  [/agn_in_[A-Za-z0-9_-]{40,}/g, '[REDACTED:agnoclast-ingest-key]'],
   [/sk-ant-oat\d{2}-[A-Za-z0-9_-]{20,}/g, '[REDACTED:anthropic-oauth]'],
   [/sk-ant-api\d{2}-[A-Za-z0-9_-]{20,}/g, '[REDACTED:anthropic-key]'],
   [/sk-ant-[A-Za-z0-9_-]{20,}/g, '[REDACTED:anthropic]'],

package/lib/server.mjs

@@ -19,11 +19,32 @@ import { repoFullNameFrom, workingFilesFrom } from './capture.mjs'
 import { findTranscript, createWorkedFilesTracker } from './working_files.mjs'
 import { spawnObligationWorker } from './obligations_worker.mjs'
 import { renderObligations } from './obligations_render.mjs'
+import { formatCreated, formatDryRun, formatSources, homeFromArgs, pickSource, renderHomeProblem } from './custom_sources.mjs'
 
 // Reactive red-link triage (Mechanism 2). On a read_page miss, ask the server whether the name is a
 // tracked wanted page, whether a bare node exists for it, and whether it's a deliberately demoted page,
 // and turn that into an actionable prompt. Wording lives in ./red_link_triage.mjs (pure + tested).
 // Returns '' on any error so a miss never gets worse.
+/**
+ * A page name held by pages in more than one brain: list them, each with the ref that picks it. The page
+ * read already returns every match (matches[] with brain + ref), so this reuses it instead of leaving the
+ * caller at a bare 409. Never throws — a failure falls back to the generic advice.
+ */
+async function ambiguousPageHint(base, token, kind, name) {
+  const generic = `"${name}" names a page in more than one of your brains. Call read_page "${name}" to see each one with its ref, then pass that ref.`
+  try {
+    const res = await fetchCortex(`${base}/api/brain/page?kind=${kind}&key=${encodeURIComponent(name)}`, { headers: { Authorization: `Bearer ${token}` } })
+    if (!res.ok) return generic
+    const page = await res.json()
+    const matches = Array.isArray(page?.matches) ? page.matches.filter((m) => m.ref) : []
+    if (!matches.length) return generic
+    return [`"${name}" names a page in ${matches.length} of your brains — pass the ref of the one you mean:`,
+      ...matches.map((m) => `  - "${m.title ?? name}" in ${m.brain ?? 'a brain'} — ref: ${m.ref}`)].join('\n')
+  } catch {
+    return generic
+  }
+}
+
 async function redLinkTriage(BASE, TOKEN, name) {
   try {
     const r = await fetchCortex(`${BASE}/api/brain/red-link?name=${encodeURIComponent(name)}`, {
@@ -1810,16 +1831,20 @@ function renderNudge(payload) {
         expand: z.boolean().optional().describe('identifier names only: also list recent visible timeline events for this identifier (default: home + count)'),
         history: z.boolean().optional().describe('node names only: return the node\'s TIMELINE (events joined via its [[repo:…]] stamps, reverse-chron, viewer-visible) instead of the page body. The page is the present; this is the history.'),
         version: z.string().optional().describe('read a HISTORICAL version of this page instead of the current one: a rev_no (e.g. "3") or a content_hash from page_history. Use page_history first to see the versions, then rollback_page to restore one.'),
+        ref: z.string().optional().describe('the page\'s ref (read_page prints it as `ref:`). Addresses exactly one page, so use it when a name exists in more than one brain — history and version reads refuse an ambiguous name and list the refs to choose from.'),
       },
     },
-    async ({ name, kind, expand, history, version }) => {
+    async ({ name, kind, expand, history, version, ref }) => {
       const k = kind ?? 'project'
+      // A ref addresses exactly one page; a name can match one page in each of several brains.
+      const address = (extra = {}) => new URLSearchParams(ref ? { ref, ...extra } : { kind: k, key: name, ...extra })
       // PAGE HISTORY (Part A): a specific version reads one historical body, resolved within this page's
       // own history. Not for identifier-shaped names (those are join keys, handled below).
       if (version && !/^[a-z][a-z0-9_-]*:.+/i.test(name)) {
         try {
-          const qs = new URLSearchParams({ kind: k, key: name, version })
+          const qs = address({ version })
           const vr = await fetchCortex(`${BASE}/api/brain/page?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+          if (vr.status === 409) return { content: [{ type: 'text', text: await ambiguousPageHint(BASE, TOKEN, k, name) }] }
           if (vr.status === 404) return { content: [{ type: 'text', text: `No version "${version}" for "${name}" (or you can't see it). Use page_history "${name}" to list its versions.` }] }
           if (!vr.ok) {
             const d = classify(vr.status, vr.headers.get('content-type'), await vr.text(), vr.headers.get('x-vercel-id'))
@@ -1834,9 +1859,12 @@ function renderNudge(payload) {
       // PER-NODE TIMELINE (slice 4): history = the projection over the node's identifier stamps.
       if (history && !/^[a-z][a-z0-9_-]*:.+/i.test(name)) {
         try {
-          const qs = new URLSearchParams({ kind: k, key: name })
+          const qs = address()
           const r = await fetchCortex(`${BASE}/api/node/timeline?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
           if (r.status === 404) return { content: [{ type: 'text', text: `No ${k} named "${name}" — cannot project a timeline.` }] }
+          // Two brains hold a page by this name. Say which, with the ref for each, rather than a bare 409 —
+          // "Agnoclast API 409: ambiguous_page_name" was a dead end (Reader Engine, 2026-09-29).
+          if (r.status === 409) return { content: [{ type: 'text', text: await ambiguousPageHint(BASE, TOKEN, k, name) }] }
           if (!r.ok) {
             const d = classify(r.status, r.headers.get('content-type'), await r.text(), r.headers.get('x-vercel-id'))
             return toolError(`Could not read the timeline for "${name}": ${d.message}`)
@@ -1868,6 +1896,8 @@ function renderNudge(payload) {
           }
           for (const e of t.events) lines.push(`- ${String(e.occurredAt).slice(0, 10)} · ${e.source} · ${e.summary}`)
           if (!t.events.length) lines.push('(no events visible to you yet on these joins)')
+          // The timeline is a list of headlines. The records themselves — every word — are one call away.
+          else lines.push(`Full text of the records on this page: list_records page:"${t.ref ?? ref ?? name}" (order:"oldest" reads them in sequence; offset pages past 50).`)
           if (t.siblings?.length) lines.push(`Sibling homes (share a stamp — bridges, not history): ${t.siblings.map((s) => `"${s.title}"`).join(', ')}`)
           return { content: [{ type: 'text', text: lines.join('\n') }] }
         } catch (e) {
@@ -1915,7 +1945,7 @@ function renderNudge(payload) {
       }
       let res
       try {
-        res = await fetchCortex(`${BASE}/api/brain/page?kind=${k}&key=${encodeURIComponent(name)}`,
+        res = await fetchCortex(`${BASE}/api/brain/page?${address()}`,
           { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
         return toolError(`Could not read "${name}": ${e.message}`)
@@ -3857,9 +3887,10 @@ function renderNudge(payload) {
         role: z.enum(['member', 'manager', 'owner']).optional().describe("their role in this brain (default 'member'). NOTE: only owner/manager can see records scoped to people below them"),
         brain: z.string().optional().describe('which brain, by name or org id. Optional when planning; REQUIRED with execute:true. Pass the org id when a name matches more than one of your brains'),
         execute: z.boolean().optional().describe('default false. false = report the plan only. true = actually add them — not undoable through the API, and requires an explicit brain'),
+        inherit_page_id: z.string().optional().describe("an existing PERSON page in that brain that becomes their user page (ADR-0023). The plan lists candidates; ask the user which, or omit for a new page"),
       },
     },
-    async ({ email, name, title, role, brain, execute }) => {
+    async ({ email, name, title, role, brain, execute, inherit_page_id }) => {
       const addr = (email ?? '').trim().toLowerCase()
       if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(addr)) return toolError(`"${email}" does not look like an email address.`)
 
@@ -3951,7 +3982,7 @@ function renderNudge(payload) {
           done = await fetchCortex(`${BASE}/api/invite`, {
             method: 'POST',
             headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-            body: JSON.stringify({ ...payload, brain: target.orgId }),
+            body: JSON.stringify({ ...payload, brain: target.orgId, ...(inherit_page_id ? { inheritPageId: inherit_page_id } : {}) }),
           })
         } catch (e) {
           return toolError(`Could not add ${payload.email} to ${target.name}: ${e.message}`)
@@ -3969,15 +4000,36 @@ function renderNudge(payload) {
         const how = r.existingAccount
           ? 'They already had an Agnoclast account, so they keep their current login and simply gain this brain.'
           : `A new account was created. Temporary password: ${r.password} — they must change it on first sign-in.`
-        return { content: [{ type: 'text', text: `Added ${payload.name} <${payload.email}> to ${target.name} as ${payload.role}, placed under you.\n${how}\n\nThis cannot be undone through the API — removing a membership currently needs direct database access.` }] }
+        const page = r.userPage?.status
+          ? `\nTheir page in ${target.name}: ${r.userPage.status}${r.userPage.error ? ` (${r.userPage.error})` : ''}.`
+          : ''
+        return { content: [{ type: 'text', text: `Added ${payload.name} <${payload.email}> to ${target.name} as ${payload.role}, placed under you.\n${how}${page}\n\nThis cannot be undone through the API — removing a membership currently needs direct database access.` }] }
       }
 
+      // ADR-0023: does this brain already have a page about them? The inviter decides — list, never pick.
+      let pageLines = []
+      try {
+        const cr = await fetchCortex(`${BASE}/api/invite/candidates`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ brain: target.orgId, name: payload.name, email: payload.email }),
+        })
+        if (cr.ok) {
+          const { candidates = [], suggested = null } = await cr.json()
+          pageLines = candidates.length
+            ? ['', 'Existing pages in this brain that may be them — ask the user whether one should become their page (pass inherit_page_id), or omit it for a new page:',
+               ...candidates.map((c) => `  - "${c.title}"  [${c.documentId}]  matched by ${c.matchedBy.join('+')}${c.documentId === suggested ? '  (likely them)' : ''}`)]
+            : ['', 'No existing page about them in this brain — they get a new one.']
+        }
+      } catch { /* the plan still stands without the lookup */ }
+
       const text = [
         `Ready to add ${payload.name} <${payload.email}> to ${target.name} as ${payload.role}.`,
         '',
         `  brain      ${target.name}  [${target.orgId}]`,
         `  your role  ${target.role} — you may add people here`,
         `  manager    you  [${target.userId}]  (they are placed under you)`,
+        ...pageLines,
         '',
         'Nothing has happened yet. To go ahead, re-run with execute:true and the same brain —',
         `or do it yourself at ${BASE}/?invite=1 with these values:`,
@@ -4084,17 +4136,27 @@ function renderNudge(payload) {
     'list_records',
     {
       title: 'List activity records (filtered)',
-      description: 'List recent activity records you can see, filtered by type, project, and recency. RLS-scoped. Use to enumerate "what happened on project X this week" or "recent meetings". Returns each record\'s FULL summary + id — never a truncated preview, so what you get back is the whole record you are permitted to read (use an id with request_file to ask its owner for the original file).',
+      description: 'List recent activity records you can see, filtered by type, project, page, source and recency. RLS-scoped. Use to enumerate "what happened on project X this week", "recent meetings", or EVERYTHING FILED ON A PAGE — pass `page` (its name or ref) to read a channel\'s items or a project page\'s records, with order:"oldest" to read a series in sequence, `offset` to page past 50, and `match` to narrow to records mentioning something. A long result holds whole records back and tells you the offset to resume from. Returns each record\'s FULL summary + id — never a truncated preview, so what you get back is the whole record you are permitted to read (use an id with request_file to ask its owner for the original file).',
       inputSchema: {
         type: z.string().optional().describe("record type, e.g. 'meeting', 'comm', 'activity', 'ai_session', 'doc', 'note'"),
         project: z.string().optional().describe('project key to filter to (e.g. "cortex")'),
         since_days: z.number().optional().describe('only records from the last N days'),
         limit: z.number().optional().describe('max rows (1-50, default 20)'),
         session: z.string().optional().describe('a session id — returns every record that session produced, INCLUDING the separate halves of a log that was split across brains. Segmented logs share a sessionId and never link to each other, so this is the only way to reassemble one. RLS-scoped: you get the halves you are cleared for and cannot tell whether others exist'),
+        page: z.string().optional().describe('a page — its name or its ref (from read_page) — to list the records filed on it. A name held by pages in several brains lists them all, each row tagged with its brain; pass the ref to pick one.'),
+        source: z.string().optional().describe("a record source, e.g. 'custom' (custom sources), 'github', 'email', 'imessage', 'meeting'"),
+        order: z.enum(['newest', 'oldest']).optional().describe('newest first (default), or oldest first to read a series in sequence'),
+        offset: z.number().optional().describe('skip this many records — page through more than 50 by calling again with offset 50, 100…'),
+        match: z.string().optional().describe('only records whose title or text contains this (case-insensitive, literal) — e.g. one book on a channel that carries several, one ticket in a queue'),
       },
     },
-    async ({ type, project, since_days, limit, session }) => {
+    async ({ type, project, since_days, limit, session, page, source, order, offset, match }) => {
       const qs = new URLSearchParams()
+      if (page) qs.set('page', page)
+      if (match) qs.set('match', match)
+      if (source) qs.set('source', source)
+      if (order) qs.set('order', order)
+      if (offset != null) qs.set('offset', String(offset))
       if (type) qs.set('type', type)
       if (project) qs.set('project', project)
       if (since_days != null) qs.set('since_days', String(since_days))
@@ -4115,6 +4177,151 @@ function renderNudge(payload) {
     },
   )
 
+  // ── custom sources: set up, list, re-home (Theron, 2026-09-29) ─────────────────────────────────
+  // "I don't think it's that good of an idea to let the user do the whole setup without having an agent
+  // involved." The agent can read the system being connected, describe what its data is ABOUT, and judge
+  // which existing page is its home — and the server holds it to that: a new page is refused while any
+  // page that may already be about it has not been set aside by id. Formatting: custom_sources.mjs.
+  const homeArgs = {
+    home_page: z.string().optional().describe('file onto this EXISTING page — an id from a candidate list, or a ref read_page printed. Preferred: one page per subject'),
+    new_page_title: z.string().optional().describe('make a NEW page with this title instead. Refused while any existing page may be about the same thing, until each is listed in not_any_of'),
+    new_page_brain: z.string().optional().describe('the brain for a new page, when you are in more than one'),
+    not_any_of: z.array(z.string()).optional().describe('the ids of EVERY candidate page you looked at and set aside — required to make a new page when candidates exist'),
+    reason: z.string().optional().describe('why none of those pages is the home — kept in the new page\'s history'),
+  }
+  const cannot = async (what, res) => {
+    const body = await res.text()
+    let j = null
+    try { j = JSON.parse(body) } catch { /* not JSON */ }
+    if (j && (res.status === 409 || res.status === 400 || res.status === 404 || res.status === 403) && (j.error || j.message)) {
+      return toolError(`${what}: ${j.candidates || j.brains || String(j.error).startsWith('home') || j.error === 'reason_required' || j.error === 'cannot_write_brain' ? renderHomeProblem(j) : (j.message ?? j.detail ?? j.error)}`)
+    }
+    return toolError(`${what}: ${classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message}`)
+  }
+
+  server.registerTool(
+    'list_custom_sources',
+    {
+      title: 'List your custom sources (with their field mappings)',
+      description: 'Your CUSTOM SOURCES — systems that push data into Agnoclast with a write-only ingest key (a script\'s output, a ticketing tool, a CRM, a dashboard). For each: its id, the page it files onto (with that page\'s ref), its FIELD MAPPING — which field of a pushed item is its id, title, main text, time — its key prefix and when the key was last used. Read this BEFORE writing or fixing anything that pushes to a source: the script\'s items must match the mapping. The key itself is never shown again (create_custom_source shows it once; the Data sources page rotates it).',
+      inputSchema: {},
+    },
+    async () => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/custom-connectors`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      } catch (e) {
+        return toolError(`Could not list custom sources: ${e.message}`)
+      }
+      if (!res.ok) return cannot('Could not list custom sources', res)
+      const j = await res.json()
+      return { content: [{ type: 'text', text: formatSources(j.connectors) }] }
+    },
+  )
+
+  server.registerTool(
+    'create_custom_source',
+    {
+      title: 'Set up a custom source (dry run first)',
+      description: [
+        'Set up a CUSTOM SOURCE — something Agnoclast has no connector for (a script\'s output, a ticketing tool, a CRM, a dashboard) — so it can push items with a write-only key. Do it WITH the person:',
+        '1. Find ONE REAL item the system produces — read its code, its output files or an export. Never invent one: a made-up sample becomes a real record the moment it is sent.',
+        '2. Call with dry_run:true, name, shape, description and that sample. You get the field mapping (suggested from the sample when you pass none), how the sample will arrive, and where items would file. Pages that may ALREADY be about this — the same name, a similar name, or pages whose text is about it — are listed: read them (read_page) and decide with the person.',
+        '3. Call again without dry_run. Prefer home_page:<id or ref> to file onto a page that exists. A new page (new_page_title) is refused until not_any_of lists every candidate and reason says why none fits — a slightly different name is not enough to get a duplicate.',
+        '4. The KEY is in the reply ONCE. Store it outside any repo (a key file, chmod 600, or an env var); never commit it or paste it anywhere.',
+        '5. Wire the system to POST items, send the real sample, and confirm it landed with list_records page:<the home\'s ref> source:"custom".',
+        'mode:"ingest" sends each item to the pile to be sorted instead — for mixed data that belongs on many pages. Reference: https://agnoclast.com/docs/custom-sources',
+      ].join('\n'),
+      inputSchema: {
+        name: z.string().describe('what the source is called, e.g. "Reader Engine" or "HaloITSM tickets"'),
+        description: z.string().describe('what this data is ABOUT, in a sentence or two — its subject, not its format (e.g. "chapter-by-chapter results of my reader-engine simulation, where AI reader personas read my novels"). Searched against every page you can read to find the one it belongs on'),
+        shape: z.enum(['message', 'event', 'document', 'record']).describe('message = emails, chats, replies · event = ticket changes, alerts, CRM updates · document = notes, transcripts, reports · record = rows, metrics, anything else'),
+        purpose: z.enum(['communication', 'work', 'reference', 'metrics']).describe('sets defaults only'),
+        sample: z.record(z.string(), z.any()).optional().describe('ONE real item, exactly as the system will send it (a JSON object)'),
+        mapping: z.record(z.string(), z.any()).optional().describe('which field plays which role, as dot paths into one item: { id, time, title, body, group, url, people: [..] }. Omit to have it suggested from the sample'),
+        mode: z.enum(['channel', 'ingest']).optional().describe('channel (default) = every item files onto one page as it arrives · ingest = each item waits in the pile to be sorted'),
+        ...homeArgs,
+        dry_run: z.boolean().optional().describe('true = show the mapping, the sample preview and the home (or the candidate pages) and create NOTHING. Do this first'),
+      },
+    },
+    async (a) => {
+      const home = homeFromArgs(a, a.name)
+      const body = {
+        name: a.name, description: a.description, shape: a.shape, purpose: a.purpose,
+        ...(a.sample ? { sample: a.sample } : {}), ...(a.mapping ? { mapping: a.mapping } : {}),
+        ...(a.mode ? { mode: a.mode } : {}), ...(home ? { home } : {}), ...(a.dry_run ? { dryRun: true } : {}),
+      }
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/custom-connectors`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify(body),
+          // A dry run writes nothing, so it may be retried; a real create is a POST and never is.
+        }, a.dry_run ? { idempotent: true } : {})
+      } catch (e) {
+        return toolError(`Could not set up the source: ${e.message}`)
+      }
+      if (!res.ok) return cannot(a.dry_run ? 'Dry run refused' : 'Not created', res)
+      const j = await res.json()
+      const text = j.dryRun ? formatDryRun(j) : formatCreated(j, (slug) => `~/.agnoclast/keys/${slug}`)
+      return { content: [{ type: 'text', text }] }
+    },
+  )
+
+  server.registerTool(
+    'set_custom_source_home',
+    {
+      title: 'Change where a custom source files',
+      description: 'Point one of your custom sources at a different page, or stop filing it onto a page. home_page files onto an existing page (an id or a read_page ref) — items it already sent INTO THAT PAGE\'S BRAIN are attached there too (items in another brain stay put; move_record moves them), and the old page stops receiving new ones (what is already on it stays). new_page_title makes a new page, under the same rule as create_custom_source: refused until every page that may already be about it is listed in not_any_of with a reason. mode:"ingest" stops filing onto a page: new items wait in the pile to be sorted.',
+      inputSchema: {
+        source: z.string().describe('the source — its id or its name, as list_custom_sources shows'),
+        ...homeArgs,
+        description: z.string().optional().describe('for a new page: what the source is about, searched to find pages that may already be its home'),
+        mode: z.enum(['channel', 'ingest']).optional().describe('ingest = stop filing onto a page (every new item goes to the pile)'),
+      },
+    },
+    async (a) => {
+      let list
+      try {
+        const res = await fetchCortex(`${BASE}/api/custom-connectors`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+        if (!res.ok) return cannot('Could not read your custom sources', res)
+        list = (await res.json()).connectors
+      } catch (e) {
+        return toolError(`Could not read your custom sources: ${e.message}`)
+      }
+      const picked = pickSource(list, a.source)
+      if (!picked.ok) return toolError(picked.message)
+      const src = picked.source
+      const url = `${BASE}/api/custom-connectors/${encodeURIComponent(src.id)}/channel`
+      let res
+      try {
+        if (a.mode === 'ingest') {
+          res = await fetchCortex(url, { method: 'DELETE', headers: { Authorization: `Bearer ${TOKEN}` } })
+          if (!res.ok) return cannot('Not changed', res)
+          return { content: [{ type: 'text', text: `${src.name} no longer files onto a page: new items wait in the pile to be sorted. Everything already filed stays where it is.` }] }
+        }
+        const home = homeFromArgs(a, src.name)
+        if (!home) return toolError('Say where it should file: home_page (an existing page) or new_page_title — or mode:"ingest" to stop filing onto a page.')
+        res = await fetchCortex(url, {
+          method: 'PUT',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ home }),
+        })
+      } catch (e) {
+        return toolError(`Not changed: ${e.message}`)
+      }
+      if (!res.ok) return cannot('Not changed', res)
+      const j = await res.json()
+      const ch = j.channel
+      return { content: [{ type: 'text', text: [
+        `${src.name} now files onto ${ch.homeCreated ? 'a NEW page' : ''} "${ch.homeTitle}" (${ch.brain}) — ref ${ch.homeRef}.`.replace('onto  "', 'onto "'),
+        `${j.attachedExisting ?? 0} item(s) it had already sent were attached there.${j.releasedPreviousHome ? ' The previous page no longer receives new items; what is on it stays.' : ''}`,
+        `Read it: list_records page:"${ch.homeRef}" source:"custom"`,
+      ].join('\n') }] }
+    },
+  )
+
   server.registerTool(
     'my_day',
     {

package/package.json

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