@rubytech/create-maxy-code 0.1.187 → 0.1.189

package/payload/platform/plugins/memory/mcp/dist/tools/memory-lookup-by-name.js

@@ -0,0 +1,56 @@
+import { getSession } from "../lib/neo4j.js";
+import { notTrashed } from "../../../../../lib/graph-trash/dist/index.js";
+import { buildScopeAndSliceClause } from "../../../../../lib/graph-search/dist/index.js";
+const DEFAULT_LIMIT = 25;
+// Stripped from returned properties: the embedding is a large float vector that
+// only bloats agent context, and accountId is the caller's own scope (mirrors
+// memory-search's formatResult hygiene).
+const STRIPPED_PROPERTY_KEYS = new Set(["embedding", "accountId"]);
+export async function memoryLookupByName(params) {
+    const { name, accountId, labels, allowedScopes, sliceToken, agentSlug } = params;
+    const limit = params.limit ?? DEFAULT_LIMIT;
+    if (!name.trim())
+        throw new Error("name is required");
+    const scope = buildScopeAndSliceClause(allowedScopes, sliceToken, "n");
+    const labelClause = labels && labels.length > 0 ? "AND any(l IN labels(n) WHERE l IN $labels)" : "";
+    const agentClause = agentSlug
+        ? "AND n.agents IS NOT NULL AND $agentSlug IN n.agents"
+        : "";
+    const cypher = `MATCH (n)
+     WHERE n.accountId = $accountId
+       AND toLower(n.name) = toLower($name)
+       AND ${notTrashed("n")}
+       ${labelClause}
+       ${scope.clause}
+       ${agentClause}
+     RETURN elementId(n) AS nodeId, labels(n) AS labels, properties(n) AS properties
+     LIMIT toInteger($limit)`;
+    const session = getSession();
+    try {
+        const result = await session.run(cypher, {
+            accountId,
+            name,
+            limit,
+            ...(labels && labels.length > 0 ? { labels } : {}),
+            ...scope.params,
+            ...(agentSlug ? { agentSlug } : {}),
+        });
+        return result.records.map((r) => {
+            const rawProps = r.get("properties");
+            const properties = {};
+            for (const [k, v] of Object.entries(rawProps)) {
+                if (!STRIPPED_PROPERTY_KEYS.has(k))
+                    properties[k] = v;
+            }
+            return {
+                nodeId: r.get("nodeId"),
+                labels: r.get("labels"),
+                properties,
+            };
+        });
+    }
+    finally {
+        await session.close();
+    }
+}
+//# sourceMappingURL=memory-lookup-by-name.js.map

package/payload/platform/plugins/memory/mcp/dist/tools/memory-lookup-by-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-lookup-by-name.js","sourceRoot":"","sources":["../../src/tools/memory-lookup-by-name.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,8CAA8C,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+CAA+C,CAAC;AAmDzF,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,gFAAgF;AAChF,8EAA8E;AAC9E,yCAAyC;AACzC,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;AAEnE,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAA0B;IAE1B,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IACjF,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,aAAa,CAAC;IAE5C,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAEtD,MAAM,KAAK,GAAG,wBAAwB,CAAC,aAAa,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;IACvE,MAAM,WAAW,GACf,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,4CAA4C,CAAC,CAAC,CAAC,EAAE,CAAC;IAClF,MAAM,WAAW,GAAG,SAAS;QAC3B,CAAC,CAAC,qDAAqD;QACvD,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,MAAM,GAAG;;;aAGJ,UAAU,CAAC,GAAG,CAAC;SACnB,WAAW;SACX,KAAK,CAAC,MAAM;SACZ,WAAW;;6BAES,CAAC;IAE5B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE;YACvC,SAAS;YACT,IAAI;YACJ,KAAK;YACL,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClD,GAAG,KAAK,CAAC,MAAM;YACf,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAC9B,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,YAAY,CAA4B,CAAC;YAChE,MAAM,UAAU,GAA4B,EAAE,CAAC;YAC/C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC9C,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC;oBAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACxD,CAAC;YACD,OAAO;gBACL,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAW;gBACjC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAa;gBACnC,UAAU;aACX,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;AACH,CAAC"}

package/payload/platform/plugins/memory/references/graph-primitives.md

@@ -40,31 +40,40 @@ token-limit discipline the upstream server enforces.
 
 ## When the memory tools are absent
 
-If `mcp__memory__memory-write`, `mcp__memory__memory-search`,
-`mcp__memory__memory-reindex`,
-`mcp__memory__session-compact`, `mcp__memory__session-compact-status`, or
-`mcp__memory__conversation-search` is missing from your tool list, the
-memory MCP server failed to start on this device. Reply once with
-exactly:
-
-> The memory MCP server failed to start on this device. Run the admin
+The maxy MCP tool names are bound to the live registry (Task 502): the
+canonical long name `mcp__plugin_memory_memory__<tool>` is generated from the
+memory plugin's manifest, a build gate fails when any instruction names a tool
+the registry does not serve, and a PostToolUse hook turns a missing-tool call
+into a fixed envelope. So a missing memory tool is one of two distinct states,
+not the single "failed to start" the old contract assumed:
+
+- **Server dead.** None of the `mcp__plugin_memory_memory__*` tools appear in
+  your tool list at all. The per-account memory server did not start; the
+  platform's `[mcp-init-error] server=memory` line in the per-conversation
+  stream log names it.
+- **Name not registered.** The server is up and other
+  `mcp__plugin_memory_memory__*` tools are present, but a specific call returns
+  `No such tool available`. The `mcp-tool-missing` hook has already logged
+  `[mcp-tool-missing] server=memory tool=<tool>` and returned the deterministic
+  envelope you are reading.
+
+In either state, reply once with exactly:
+
+> The memory MCP server is unavailable on this device. Run the admin
 > system-status check to diagnose — do not retry by other routes.
 
-Then stop. Do not search for a similarly-named tool via `ToolSearch`, do
-not improvise via `maxy-graph-read_neo4j_cypher` (it is read-only — every
-write goes through the schema-aware memory tools), do not paraphrase.
-A missing memory tool is a deterministic failure of the per-account
-memory server: the platform's `[mcp-init-error] server=memory` line in
-the per-conversation stream log already names it; the user-facing reply
-exists so the operator knows the session cannot proceed without an
-operator-side fix (the loud-fail contract applies equally
-to graph and memory tool initialisation).
+Then stop. Do not search for a similarly-named tool via `ToolSearch`, do not
+improvise via `mcp__plugin_graph_graph__maxy-graph-read_neo4j_cypher` (it is
+read-only — every write goes through the schema-aware memory tools), do not
+paraphrase, do not describe the server as "warming up". The reply exists so the
+operator knows the session cannot proceed without an operator-side fix (the
+loud-fail contract applies equally to graph and memory tool initialisation).
 
 ## Mutation intents
 
 The graph tools above are read-only. Every write intent has a schema-aware
 tool that already exists — match the user's prose to a tool in this table
-rather than improvising. `mcp__admin__admin-remove` is in your initial
+rather than improvising. `mcp__plugin_admin_admin__admin-remove` is in your initial
 tool list; the other tools below are deferred (they do not appear until
 you invoke `ToolSearch` by the exact name you pick from the table).
 Do not use `ToolSearch` to *discover* the tool by keyword — identify it
@@ -78,14 +87,14 @@ graph as a single action.
 
 | User intent | Tool | When to pick this, not the next row |
 |---|---|---|
-| "remove admin X", "take away their admin access", "revoke admin" | `mcp__admin__admin-remove` | Device-level admin offboarding — detaches the `(AdminUser)-[:ADMIN_OF]->(LocalBusiness)` edge and updates `platform/config/users.json`. Not for scrubbing personal data — use the GDPR contact-erase tools for that. |
-| "delete this specific node", "remove this entry by its id", "get rid of node X", "remove orphans", "prune", "clean up" | `mcp__memory__memory-delete` | Soft-deletes a single node by `elementId` (adds `:Trashed`, preserves relationships, snapshots unique keys, invisible to `memory-search` and any `notTrashed`-filtered read). For KnowledgeDocument, cascades to Sections and Chunks. Enumerate candidates first with a Cypher read, confirm with the user, then delete each by `elementId`. There is no bulk "delete everything without relationships" tool. Per the write doctrine (`.docs/neo4j.md` § Write doctrine), **new** orphans should be impossible — every writer now rejects zero-edge calls at the MCP tool-surface. Existing orphans from legacy data are legitimate backfill candidates but are not produced by any live writer; if you see a freshly-created orphan, it is a bug in a writer that bypassed `writeNodeWithEdges`, not expected state. |
-| "undo that delete", "I deleted X by mistake, bring it back", "restore the contact I just trashed" | `mcp__memory__memory-restore` | Removes `:Trashed`, restores snapshotted unique-key properties. Fails loudly when an active node already holds the unique slot (e.g. a fresh `LocalBusiness` was created while the old one was in trash) — the error names the conflicting `elementId` so you can ask the user how to resolve. |
-| "empty the trash", "purge old soft-deletes", "what's been sitting in trash and ready to clear" | `mcp__memory__memory-empty-trash` | Hard-deletes trashed nodes whose `trashedAt` is older than `graceDays` (default 30); `dryRun=true` lists candidates without mutating. Use `dryRun` first, show the list to the user, then run for real. For KnowledgeDocument candidates, the on-disk attachment directory is removed too. |
-| "scrub this conversation's memory", "remove this claim the bot picked up", "forget what we said in that thread" | `mcp__memory__conversation-memory-expunge` | Removes deny-listable content from `:Memory` nodes scoped to one conversation. Requires an explicit pattern and sessionId. Not for deleting individual nodes — use `memory-delete`. |
-| "update a property", "fix a typo in a node", "change the role field on X", "null this poisonous string" | `mcp__memory__memory-update` | Targeted property edit on an existing node, schema-validated. Use to null individual string properties matching a deny-list entry once you've identified the offender via a Cypher read. Not for creating new nodes — use `memory-write`. |
-| "update X by name, search didn't return it", "wire this Org but search came back empty", "I know it exists but I don't have the elementId" | `mcp__memory__memory-update-by-name` | Repair surface for the case where `memory-search` cannot return a row you know exists by name. Resolves the unique `(label, name, accountId)` tuple, then delegates to `memory-update`. Rejects loudly on zero or ambiguous matches (the rejection lists candidate elementIds so you can pick one). Trashed nodes excluded. Use this only after `memory-search` failed — for normal updates, get the elementId from search and call `memory-update` directly. |
-| "don't surface these substrings in future memory results", "watch for this string" | `mcp__memory__graph-prune-denylist-add` | Records a substring as operator-curated signal. Nothing auto-applies it — when a subsequent memory-search or cypher read surfaces a match, use `memory-update` or `memory-delete` with discretion to scrub it. |
+| "remove admin X", "take away their admin access", "revoke admin" | `mcp__plugin_admin_admin__admin-remove` | Device-level admin offboarding — detaches the `(AdminUser)-[:ADMIN_OF]->(LocalBusiness)` edge and updates `platform/config/users.json`. Not for scrubbing personal data — use the GDPR contact-erase tools for that. |
+| "delete this specific node", "remove this entry by its id", "get rid of node X", "remove orphans", "prune", "clean up" | `mcp__plugin_memory_memory__memory-delete` | Soft-deletes a single node by `elementId` (adds `:Trashed`, preserves relationships, snapshots unique keys, invisible to `memory-search` and any `notTrashed`-filtered read). For KnowledgeDocument, cascades to Sections and Chunks. Enumerate candidates first with a Cypher read, confirm with the user, then delete each by `elementId`. There is no bulk "delete everything without relationships" tool. Per the write doctrine (`.docs/neo4j.md` § Write doctrine), **new** orphans should be impossible — every writer now rejects zero-edge calls at the MCP tool-surface. Existing orphans from legacy data are legitimate backfill candidates but are not produced by any live writer; if you see a freshly-created orphan, it is a bug in a writer that bypassed `writeNodeWithEdges`, not expected state. |
+| "undo that delete", "I deleted X by mistake, bring it back", "restore the contact I just trashed" | `mcp__plugin_memory_memory__memory-restore` | Removes `:Trashed`, restores snapshotted unique-key properties. Fails loudly when an active node already holds the unique slot (e.g. a fresh `LocalBusiness` was created while the old one was in trash) — the error names the conflicting `elementId` so you can ask the user how to resolve. |
+| "empty the trash", "purge old soft-deletes", "what's been sitting in trash and ready to clear" | `mcp__plugin_memory_memory__memory-empty-trash` | Hard-deletes trashed nodes whose `trashedAt` is older than `graceDays` (default 30); `dryRun=true` lists candidates without mutating. Use `dryRun` first, show the list to the user, then run for real. For KnowledgeDocument candidates, the on-disk attachment directory is removed too. |
+| "scrub this conversation's memory", "remove this claim the bot picked up", "forget what we said in that thread" | `mcp__plugin_memory_memory__conversation-memory-expunge` | Removes deny-listable content from `:Memory` nodes scoped to one conversation. Requires an explicit pattern and sessionId. Not for deleting individual nodes — use `memory-delete`. |
+| "update a property", "fix a typo in a node", "change the role field on X", "null this poisonous string" | `mcp__plugin_memory_memory__memory-update` | Targeted property edit on an existing node, schema-validated. Use to null individual string properties matching a deny-list entry once you've identified the offender via a Cypher read. Not for creating new nodes — use `memory-write`. |
+| "update X by name, search didn't return it", "wire this Org but search came back empty", "I know it exists but I don't have the elementId" | `mcp__plugin_memory_memory__memory-update-by-name` | Repair surface for the case where `memory-search` cannot return a row you know exists by name. Resolves the unique `(label, name, accountId)` tuple, then delegates to `memory-update`. Rejects loudly on zero or ambiguous matches (the rejection lists candidate elementIds so you can pick one). Trashed nodes excluded. Use this only after `memory-search` failed — for normal updates, get the elementId from search and call `memory-update` directly. |
+| "don't surface these substrings in future memory results", "watch for this string" | `mcp__plugin_memory_memory__graph-prune-denylist-add` | Records a substring as operator-curated signal. Nothing auto-applies it — when a subsequent memory-search or cypher read surfaces a match, use `memory-update` or `memory-delete` with discretion to scrub it. |
 
 **Never run `cypher-shell` via `Bash` to work around the read-only tool.**
 The admin session's `Bash` surface has no path to the per-brand Neo4j
@@ -107,7 +116,7 @@ MATCH (a:AdminUser) WHERE NOT (a)--() RETURN elementId(a), a.userId, a.createdAt
 ```
 
 Show the list to the user. For each confirmed entry, call
-`mcp__memory__memory-delete` with the `elementId`. Do not batch-delete
+`mcp__plugin_memory_memory__memory-delete` with the `elementId`. Do not batch-delete
 by pattern — on 2026-04-20 an autonomous orphan-delete rule wiped 19
 nodes in one call, with no property recovery possible. Structural mass-
 deletion by shape is banned; discretion per node is the only sanctioned

package/payload/platform/plugins/obsidian-import/PLUGIN.md

@@ -18,7 +18,7 @@ The admin agent delegates to `specialists:database-operator` when the operator d
 
 ## How parsing happens
 
-The skill does not parse markdown. Vault traversal, frontmatter YAML, wikilink regex, tag scanning, daily-notes detection, and attachment resolution all happen server-side inside `mcp__memory__obsidian-vault-import` (memory plugin). The skill is the operator-facing conversation surface only: confirm owner → select filters → invoke the tool with `mode='dry-run'` → present ambiguities → invoke with `mode='commit'` and the operator's resolutions.
+The skill does not parse markdown. Vault traversal, frontmatter YAML, wikilink regex, tag scanning, daily-notes detection, and attachment resolution all happen server-side inside `mcp__plugin_memory_memory__obsidian-vault-import` (memory plugin). The skill is the operator-facing conversation surface only: confirm owner → select filters → invoke the tool with `mode='dry-run'` → present ambiguities → invoke with `mode='commit'` and the operator's resolutions.
 
 ## Intra-plugin growth
 

package/payload/platform/scripts/check-canonical-tool-names.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Strong build gate for canonical maxy MCP tool names (Task 502).
+//
+// Two checks, both must pass:
+//   1. Regenerate-and-diff: the committed generated artifact
+//      (canonical-tool-names.generated.ts) must byte-match a fresh generation
+//      from platform/plugins/*/PLUGIN.md. A stale artifact fails the build —
+//      this is what stops a PLUGIN.md tool add/remove from drifting away from
+//      the names instructions are bound to.
+//   2. Instruction-name validation: every `mcp__...` tool name in an
+//      instruction file (specialist templates, agent prompts, plugin
+//      references/skills, PLUGIN.md prose) that targets a MAXY plugin must be
+//      the canonical long prefix AND must exist in the live set. A short-prefix
+//      maxy name (mcp__<plugin>__<tool>) fails — it must be long. An unknown
+//      long-prefix maxy name fails — typo or stale. Non-maxy bridge namespaces
+//      (playwright, etc.) are ignored: their tool names are upstream-owned.
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { computeCanonicalToolNames, MAXY_CODE_ROOT } from './lib/canonical-tool-names.mjs'
+import { renderArtifact, renderPluginsList } from './generate-canonical-tool-names.mjs'
+
+const GENERATED = join(
+  MAXY_CODE_ROOT, 'platform', 'services', 'claude-session-manager', 'src',
+  'canonical-tool-names.generated.ts',
+)
+const PLUGINS_TXT = join(
+  MAXY_CODE_ROOT, 'platform', 'plugins', 'admin', 'hooks', 'lib',
+  'maxy-mcp-plugins.txt',
+)
+
+const SCAN_DIRS = [
+  join(MAXY_CODE_ROOT, 'platform', 'templates', 'specialists', 'agents'),
+  join(MAXY_CODE_ROOT, 'platform', 'plugins'),
+]
+const SCAN_EXT = new Set(['.md'])
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'payload', '__tests__'])
+// mcp__<seg>__<tool>  — seg may itself contain `_` (long prefix plugin_a_b).
+const TOOL_RE = /mcp__([A-Za-z0-9-]+(?:_[A-Za-z0-9-]+)*)__([A-Za-z0-9_-]+)/g
+
+function* walk(dir) {
+  let entries
+  try { entries = readdirSync(dir) } catch { return }
+  for (const e of entries.sort()) {
+    if (e.startsWith('.') || SKIP_DIRS.has(e)) continue
+    const p = join(dir, e)
+    let st
+    try { st = statSync(p) } catch { continue }
+    if (st.isDirectory()) { yield* walk(p); continue }
+    const ext = e.includes('.') ? '.' + e.split('.').pop() : ''
+    if (SCAN_EXT.has(ext)) yield p
+  }
+}
+
+function main() {
+  const { plugins, names } = computeCanonicalToolNames()
+  const maxyPlugins = new Set(plugins)
+  const canonical = new Set(names)
+
+  // Check 1 — regenerate-and-diff both generated outputs.
+  let driftError = null
+  const staleOutputs = []
+  if ((existsSync(GENERATED) ? readFileSync(GENERATED, 'utf8') : '') !== renderArtifact()) staleOutputs.push(GENERATED)
+  if ((existsSync(PLUGINS_TXT) ? readFileSync(PLUGINS_TXT, 'utf8') : '') !== renderPluginsList()) staleOutputs.push(PLUGINS_TXT)
+  if (staleOutputs.length > 0) {
+    driftError =
+      `[gate] canonical-tool-names: GENERATED ARTIFACT STALE.\n` +
+      staleOutputs.map((p) => `  ${p}`).join('\n') + '\n' +
+      `  Regenerate: cd platform && npm run gen:canonical-tools`
+  }
+
+  // Check 2 — instruction-name validation.
+  const violations = []
+  for (const root of SCAN_DIRS) {
+    for (const file of walk(root)) {
+      const text = readFileSync(file, 'utf8')
+      for (const m of text.matchAll(TOOL_RE)) {
+        const seg = m[1]
+        const full = m[0]
+        // Skip glob patterns in prose (`mcp__plugin_x_x__*`): the `*` is not a
+        // tool char so the match captured a partial name, not a real reference.
+        if (text[m.index + full.length] === '*') continue
+        if (seg.startsWith('plugin_')) {
+          // Long prefix mcp__plugin_<plugin>_<server>__<tool>.
+          const inner = seg.slice('plugin_'.length)
+          // plugin === server for maxy; the long prefix is `<plugin>_<plugin>`.
+          const plugin = [...maxyPlugins].find((p) => inner === `${p}_${p}`)
+          if (!plugin) continue // non-maxy bridge (playwright) — upstream-owned.
+          if (!canonical.has(full)) {
+            violations.push({ file, name: full, why: 'unknown maxy tool (typo or stale)' })
+          }
+        } else if (maxyPlugins.has(seg)) {
+          // Short prefix mcp__<maxyplugin>__<tool> — must be long now.
+          violations.push({ file, name: full, why: `short prefix for maxy plugin '${seg}' — use canonical long name` })
+        }
+      }
+    }
+  }
+
+  const failed = driftError || violations.length > 0
+  if (driftError) console.error(driftError)
+  if (violations.length > 0) {
+    console.error('[gate] canonical-tool-names: instruction files name tools outside the live set:')
+    for (const v of violations) console.error(`  ${v.file.replace(MAXY_CODE_ROOT + '/', '')}: ${v.name} — ${v.why}`)
+  }
+  if (failed) process.exit(1)
+  console.log(`[gate] check-canonical-tool-names: PASS (${names.length} canonical names, scanned instruction files)`)
+}
+
+main()

package/payload/platform/scripts/generate-canonical-tool-names.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Generator: writes the committed canonical maxy MCP tool-name artifact from
+// every platform/plugins/<dir>/PLUGIN.md. Run via `npm run gen:canonical-tools`
+// (platform). The strong build gate (check-canonical-tool-names.mjs) regenerates
+// in-memory and fails the build if the committed artifact has drifted.
+import { writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { computeCanonicalToolNames, MAXY_CODE_ROOT } from './lib/canonical-tool-names.mjs'
+
+const OUT = join(
+  MAXY_CODE_ROOT, 'platform', 'services', 'claude-session-manager', 'src',
+  'canonical-tool-names.generated.ts',
+)
+
+// Plain newline-delimited maxy plugin list the deterministic missing-tool hook
+// (bash) reads to tell a maxy server (mcp__plugin_<p>_<p>__) from a third-party
+// bridge that shares the same long-prefix shape (Playwright etc.).
+const PLUGINS_TXT = join(
+  MAXY_CODE_ROOT, 'platform', 'plugins', 'admin', 'hooks', 'lib',
+  'maxy-mcp-plugins.txt',
+)
+
+export function renderPluginsList() {
+  const { plugins } = computeCanonicalToolNames()
+  return plugins.join('\n') + '\n'
+}
+
+export function renderArtifact() {
+  const { plugins, names } = computeCanonicalToolNames()
+  const body = [
+    '// GENERATED — do not edit by hand.',
+    '// Source: platform/plugins/*/PLUGIN.md (tools: + hidden: blocks).',
+    '// Regenerate: cd platform && npm run gen:canonical-tools',
+    '// Gate: platform/scripts/check-canonical-tool-names.mjs fails the build on drift.',
+    '//',
+    '// Canonical long-prefix names every maxy MCP tool is served under by the',
+    '// installed-plugin channel: mcp__plugin_<dir>_<dir>__<tool>.',
+    '',
+    '/** Directory basenames of maxy platform plugins that expose a tool surface. */',
+    'export const MAXY_MCP_PLUGINS: readonly string[] = [',
+    ...plugins.map((p) => `  ${JSON.stringify(p)},`),
+    ']',
+    '',
+    '/** Every canonical maxy MCP tool name (long prefix), sorted. */',
+    'export const CANONICAL_MAXY_TOOL_NAMES: readonly string[] = [',
+    ...names.map((n) => `  ${JSON.stringify(n)},`),
+    ']',
+    '',
+  ].join('\n')
+  return body
+}
+
+function main() {
+  writeFileSync(OUT, renderArtifact(), 'utf8')
+  writeFileSync(PLUGINS_TXT, renderPluginsList(), 'utf8')
+  const { plugins, names } = computeCanonicalToolNames()
+  console.log(`[gen] canonical-tool-names: ${plugins.length} plugins, ${names.length} tools -> ${OUT}`)
+  console.log(`[gen] maxy-mcp-plugins.txt -> ${PLUGINS_TXT}`)
+}
+
+export { OUT, PLUGINS_TXT }
+
+if (import.meta.url === `file://${process.argv[1]}`) main()

package/payload/platform/scripts/identity-forbidden-token-check.mjs

@@ -43,14 +43,15 @@ const FORBIDDEN_HOOK_NAMES = [
 ];
 
 function stripVoiceSection(content) {
+  // Scope past the "## How you sound" section through end of file. Everything
+  // from that heading onward is voice/output/access prose that legitimately
+  // names forbidden classes and skill-load invocations (the plain-English and
+  // operator-voice passes) without being instances of them; only the
+  // behavioural prose above it is scanned.
   const lines = content.split("\n");
   const start = lines.findIndex((l) => l.trim() === "## How you sound");
   if (start === -1) return content;
-  let end = lines.length;
-  for (let i = start + 1; i < lines.length; i++) {
-    if (lines[i].startsWith("## ")) { end = i; break; }
-  }
-  return [...lines.slice(0, start), ...lines.slice(end)].join("\n");
+  return lines.slice(0, start).join("\n");
 }
 
 export function runIdentityForbiddenTokenCheck(identityContent) {

package/payload/platform/scripts/lib/canonical-tool-names.mjs

@@ -0,0 +1,88 @@
+// Shared source of truth for canonical (long-prefix) maxy MCP tool names.
+//
+// Claude Code's installed-plugin channel serves every plugin MCP tool under
+// the long prefix `mcp__plugin_<plugin>_<server>__<tool>`. For every platform
+// plugin the marketplace name, the MCP server key, and the directory basename
+// are identical, so the canonical name is deterministically
+// `mcp__plugin_<dir>_<dir>__<tool>`. This module is the single place that
+// derives those names from each `platform/plugins/<dir>/PLUGIN.md`; the
+// generator writes the committed artifact from it, the build gate diffs
+// against it, and the session-manager cross-checks its tool surface against it.
+//
+// Scope: platform plugins only. Third-party bridge servers (playwright, etc.)
+// also render under `mcp__plugin_*` but their tool names are upstream-owned and
+// are NOT part of the maxy canonical set — the drift check treats a
+// `mcp__plugin_*` name whose plugin segment is not a maxy plugin as a bridge
+// pass, never validating it against this set.
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+export const MAXY_CODE_ROOT = resolve(__dirname, '..', '..', '..')
+const PLATFORM_PLUGINS_ROOT = join(MAXY_CODE_ROOT, 'platform', 'plugins')
+
+/** Long-prefix canonical name for a platform plugin tool. plugin === server
+ *  === directory basename for every platform MCP plugin. */
+export function canonicalToolName(plugin, tool) {
+  return `mcp__plugin_${plugin}_${plugin}__${tool}`
+}
+
+function extractFrontmatter(md) {
+  if (!md.startsWith('---')) return null
+  const end = md.indexOf('\n---', 3)
+  if (end < 0) return null
+  return md.slice(3, end)
+}
+
+// Collect `- name: <x>` entries under a bare `tools:` block and `- <x>` entries
+// under a bare `hidden:` block. Both contribute names a specialist may list in
+// its `tools:` frontmatter, so both belong to the live set.
+function parseToolNames(frontmatter) {
+  const lines = frontmatter.split('\n')
+  const names = []
+  let mode = null // 'tools' | 'hidden' | null
+  for (const line of lines) {
+    if (/^tools\s*:/.test(line)) {
+      mode = /^tools\s*:\s*$/.test(line) ? 'tools' : null
+      continue
+    }
+    if (/^hidden\s*:/.test(line)) {
+      mode = /^hidden\s*:\s*$/.test(line) ? 'hidden' : null
+      continue
+    }
+    if (/^\S/.test(line) && line.trim() !== '') { mode = null; continue }
+    if (mode === 'tools') {
+      const m = line.match(/^\s+-\s+name:\s*(.+?)\s*$/)
+      if (m) names.push(m[1])
+    } else if (mode === 'hidden') {
+      const m = line.match(/^\s+-\s+(.+?)\s*$/)
+      if (m) names.push(m[1])
+    }
+  }
+  return names
+}
+
+/** Returns { plugins, names } — `plugins` is the sorted list of maxy plugin
+ *  directory basenames that declare a tool surface; `names` is the sorted list
+ *  of canonical long-prefix tool names across all of them. */
+export function computeCanonicalToolNames(pluginsRoot = PLATFORM_PLUGINS_ROOT) {
+  const plugins = []
+  const names = new Set()
+  if (!existsSync(pluginsRoot)) return { plugins, names: [] }
+  for (const entry of readdirSync(pluginsRoot).sort()) {
+    if (entry.startsWith('.')) continue
+    const dir = join(pluginsRoot, entry)
+    try { if (!statSync(dir).isDirectory()) continue } catch { continue }
+    const manifest = join(dir, 'PLUGIN.md')
+    if (!existsSync(manifest)) continue
+    const fm = extractFrontmatter(readFileSync(manifest, 'utf-8'))
+    if (fm === null) continue
+    const toolNames = parseToolNames(fm)
+    if (toolNames.length === 0) continue
+    plugins.push(entry)
+    for (const t of toolNames) names.add(canonicalToolName(entry, t))
+  }
+  return { plugins: plugins.sort(), names: Array.from(names).sort() }
+}

package/payload/platform/scripts/setup-account.sh

@@ -127,6 +127,12 @@ cat > "$ACCOUNT_SETTINGS" << SETTINGS_EOF
           { "type": "command", "command": "bash $HOOKS_PATH/archive-ingest-surface-gate.sh" }
         ]
       },
+      {
+        "matcher": "mcp__.*",
+        "hooks": [
+          { "type": "command", "command": "bash $HOOKS_PATH/mcp-tool-missing.sh" }
+        ]
+      },
       {
         "matcher": "Write",
         "hooks": [
@@ -202,7 +208,12 @@ done
 rm -f "$ACCOUNT_DIR/.claude/agents/"*.md 2>/dev/null || true
 
 # SOUL.md — user-controlled personalisation. Only create if missing. Never overwrite.
-[ -f "$ACCOUNT_DIR/agents/admin/SOUL.md" ] || cp "$TEMPLATES_DIR/agents/admin/SOUL.md" "$ACCOUNT_DIR/agents/admin/SOUL.md"
+if [ -f "$ACCOUNT_DIR/agents/admin/SOUL.md" ]; then
+  echo "  agents/admin/SOUL.md preserved ($(wc -c < "$ACCOUNT_DIR/agents/admin/SOUL.md" | tr -d ' ') bytes)"
+else
+  cp "$TEMPLATES_DIR/agents/admin/SOUL.md" "$ACCOUNT_DIR/agents/admin/SOUL.md"
+  echo "  agents/admin/SOUL.md created ($(wc -c < "$ACCOUNT_DIR/agents/admin/SOUL.md" | tr -d ' ') bytes)"
+fi
 
 # Public agent SOUL.md + config.json — create if missing, never overwrite.
 # IDENTITY.md is handled in the Rubytech-controlled block above.

package/payload/platform/scripts/smoke-boot-services.sh

@@ -92,6 +92,7 @@ fixture_claude_session_manager() {
   cat > "$platform_root/config/brand.json" <<'BRAND'
 {
   "hostname": "smoke",
+  "productName": "Smoke",
   "domain": null
 }
 BRAND

package/payload/platform/services/claude-session-manager/dist/canonical-tool-names.d.ts

@@ -0,0 +1,7 @@
+/** Long-prefix name served by the installed-plugin channel (admin + specialist
+ *  spawns). plugin === server === plugin directory basename. */
+export declare function canonicalToolName(plugin: string, tool: string): string;
+/** Short-prefix name served by the per-spawn `--mcp-config` channel, retained
+ *  only for public-agent spawns. */
+export declare function qualifyShortToolName(plugin: string, tool: string): string;
+//# sourceMappingURL=canonical-tool-names.d.ts.map

package/payload/platform/services/claude-session-manager/dist/canonical-tool-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-tool-names.d.ts","sourceRoot":"","sources":["../src/canonical-tool-names.ts"],"names":[],"mappings":"AAaA;gEACgE;AAChE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;oCACoC;AACpC,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzE"}

package/payload/platform/services/claude-session-manager/dist/canonical-tool-names.generated.d.ts

@@ -0,0 +1,5 @@
+/** Directory basenames of maxy platform plugins that expose a tool surface. */
+export declare const MAXY_MCP_PLUGINS: readonly string[];
+/** Every canonical maxy MCP tool name (long prefix), sorted. */
+export declare const CANONICAL_MAXY_TOOL_NAMES: readonly string[];
+//# sourceMappingURL=canonical-tool-names.generated.d.ts.map

package/payload/platform/services/claude-session-manager/dist/canonical-tool-names.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-tool-names.generated.d.ts","sourceRoot":"","sources":["../src/canonical-tool-names.generated.ts"],"names":[],"mappings":"AAQA,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAiB7C,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAgLtD,CAAA"}