mikser-io-mcp 1.22.0 → 2.0.0

package/index.js

@@ -1,5 +1,5 @@
 // MCP substrate for mikser-io. The mcp plugin exposes
-// `runtime.options.mcp` (a substrate object) at factory time so other
+// the 'mcp' service (a substrate object) at factory time so other
 // plugins can register tools / resources / prompts against it at their
 // onLoaded hook with the same shape as the SDK's McpServer.
 //
@@ -44,6 +44,7 @@ import {
     explain,
     buildReport,
     requestReport,
+    faults,
     nextCycleId,
     whenCycleCompletes,
     cycleHistory,
@@ -62,6 +63,8 @@ import {
     useProvenance,
     sourcesBehind,
     sourcesOf,
+    provideService,
+    useService,
     registerTool as coreRegisterTool,
     toolNames as coreToolNames,
     toolSchema as coreToolSchema,
@@ -244,7 +247,7 @@ function wrapMutatingHandler(handler) {
         // here so every mutating tool answers the same way, and only when the
         // set actually recorded something: an id for a call that wrote
         // nothing is a handle to nothing.
-        return attachChangeSet(result, id)
+        return await attachChangeSet(result, id)
     }
 }
 
@@ -258,15 +261,15 @@ function actingPrincipal() {
     // everything else agree about who is calling.
     const principal = authContext.getStore()?.principal
     if (!principal) return 'agent'
-    const role = actingRole(principal.roles ?? [], runtime.options.roles?.catalogue ?? {})
+    const role = actingRole(principal.roles ?? [], useService('roles')?.catalogue ?? {})
     const subject = principal.subject ?? 'agent'
     return role ? `${subject} (${role})` : subject
 }
 
 // Fold the id into an MCP result's JSON text block, leaving anything else —
 // an image, an error, a non-JSON body — exactly as the tool produced it.
-function attachChangeSet(result, id) {
-    if (!findChangeSet(id)) return result
+async function attachChangeSet(result, id) {
+    if (!await findChangeSet(id)) return result
     const content = result?.content
     if (result?.isError || !Array.isArray(content)) return result
     return {
@@ -332,11 +335,24 @@ export function createMcpSubstrate() {
             const schema = coreToolSchema(name)
             if (!schema) continue
             try {
-                server.registerTool(
-                    exposed,
-                    { description: schema.description, inputSchema: zodShapeFrom(schema.inputSchema) },
-                    (args) => coreInvokeTool(name, args),
-                )
+                // normalizeInputSchema, not zodShapeFrom: a plugin registering
+                // against the engine may describe its parameters EITHER in the
+                // engine's neutral vocabulary or in zod. zodShapeFrom assumes
+                // neutral, so a real zod shape came through it as a bag of
+                // optional strings — every constraint dropped, no error, and a
+                // tool that looked registered but refused nothing.
+                let inputSchema = normalizeInputSchema(schema.inputSchema)
+                let handler = (args) => coreInvokeTool(name, args)
+                // `mutates: true` reaches here now that the engine registry
+                // carries the whole definition. Without this a mutating tool
+                // registered against the engine would take no changeSet, and
+                // its writes would be unattributable — the one failure nothing
+                // downstream can repair.
+                if (schema.mutates) {
+                    inputSchema = withChangeSetParams(inputSchema)
+                    handler = wrapMutatingHandler(handler)
+                }
+                server.registerTool(exposed, { description: schema.description, inputSchema }, handler)
                 bound.tools++
             } catch (err) {
                 runtime.engine?.logger?.debug(
@@ -735,7 +751,7 @@ function stalePackages(workingFolder) {
     substrate.registerTool(
         'mikser_ping',
         {
-            description: 'Return mikser engine identity, current lifecycle phase, and (if --server is on) where the HTTP server is reachable. Use to confirm the connection is live before issuing other tool calls and to learn the base URL for preview outputs.\n\n`plugins` lists what this mikser is built from — every installed mikser package with its purpose, version and links, and `active: true` on the ones actually running. Read it once to know what the system can do before reasoning about what it should.\n\nCheck `stale` before trusting any other tool, and before reporting a bug: it lists mikser packages installed SINCE this process booted, whose code is therefore not the code answering you. A running process never re-reads node_modules, and --watch does not change that — it reloads content, not dependencies. When `stale` is non-empty the fix is a restart, not a bug report.\n\nThe `auth` block names the ROLE this session acts as, what it may write and what it may only read — and `auth.roles` lists EVERY role on this site with the same reach, the acting one marked. That is INFORMATIONAL: report what you cannot do and stop. There is no way to request or change a role and none will be added — the listing names a person to ask, not a privilege to obtain.',
+            description: 'Return mikser engine identity, current lifecycle phase, and (if --server is on) where the HTTP server is reachable. Use to confirm the connection is live before issuing other tool calls and to learn the base URL for preview outputs.\n\n`plugins` lists what this mikser is built from — every installed mikser package with its purpose, version and links, and `active: true` on the ones actually running. Read it once to know what the system can do before reasoning about what it should.\n\nCheck `faults` before reading any empty result as a fact about the site: it is absent unless a subsystem has reported that it cannot work, and while it is present a tool may be answering emptily because it is unable to answer rather than because there is nothing to say. Each entry names the condition, when it was first and last seen, and how often — report it and stop rather than working around it.\n\nCheck `stale` before trusting any other tool, and before reporting a bug: it lists mikser packages installed SINCE this process booted, whose code is therefore not the code answering you. A running process never re-reads node_modules, and --watch does not change that — it reloads content, not dependencies. When `stale` is non-empty the fix is a restart, not a bug report.\n\nThe `auth` block names the ROLE this session acts as, what it may write and what it may only read — and `auth.roles` lists EVERY role on this site with the same reach, the acting one marked. That is INFORMATIONAL: report what you cannot do and stop. There is no way to request or change a role and none will be added — the listing names a person to ask, not a privilege to obtain.',
             inputSchema: {},
         },
         async () => ({
@@ -752,6 +768,13 @@ function stalePackages(workingFolder) {
                     // Empty is the normal case and means what it says: the code
                     // answering you is the code on disk.
                     ...stalePackages(runtime.options.workingFolder),
+                    // Subsystems that have reported themselves unable to
+                    // work. Absent is the normal case, and the reason this is
+                    // here at all: a tool answering [] because it is BROKEN
+                    // and one answering [] because nothing matched are the
+                    // same answer, and the log line that said which is a
+                    // channel an agent never reads.
+                    ...faultStatus(),
                     // What this mikser is made of. An agent can otherwise see
                     // what it may write and nothing about the machine doing
                     // the writing — and a capability like `drive:layouts`
@@ -820,8 +843,8 @@ function authStatus() {
     const authority = describeAuthority({
         capabilities: principal.capabilities,
         roles: principal.roles ?? [],
-        catalogue: runtime.options.roles?.catalogue ?? {},
-        summaries: runtime.options.roles?.summaries ?? {},
+        catalogue: useService('roles')?.catalogue ?? {},
+        summaries: useService('roles')?.summaries ?? {},
     })
     const exp = principal.claims?.exp
     if (!exp) {
@@ -1047,6 +1070,17 @@ async function readIfText(uri) {
 // Kept as a function rather than a const so each call re-reads
 // runtime.options — covers the case where --server flips on after
 // the substrate was created (rare but possible programmatically).
+// Subsystems that have reported themselves unable to work, if any.
+//
+// Omitted entirely when there are none, so presence is meaningful and a
+// healthy ping stays the short document it was. `last` is the field that says
+// whether a fault is still live: one seen only at boot and one firing every
+// cycle read the same by presence alone.
+function faultStatus() {
+    const open = faults()
+    return open.length ? { faults: open } : {}
+}
+
 function serverInfo() {
     const opts = runtime.options
     const hasInternalServer = opts.server != null && opts.port != null
@@ -1478,7 +1512,7 @@ function pinoLevelNumber(name) {
 //
 // The factory creates the substrate SYNCHRONOUSLY so other plugins
 // listed AFTER 'mcp' in the array can register tools/resources at
-// their own onLoaded hook with `if (!runtime.options.mcp) return`
+// their own onLoaded hook by asking core for the 'mcp' service
 // gating already in place from the in-core era. The plugin MUST be
 // FIRST in the user's plugins array — that's a documented invariant
 // in this repo's README.
@@ -1520,12 +1554,19 @@ export function mcp(options = {}) {
         add(runtime.options.corsExposeHeaders, ['mcp-session-id', 'mcp-protocol-version'])
     }
 
-    // Create substrate synchronously. Other plugins' factories /
-    // onLoaded hooks check `if (!runtime.options.mcp) return` before
-    // calling `mcp.simpleTool(...)` — so the substrate has to be on
-    // runtime.options.mcp by the time those run. The mcp plugin MUST
-    // be FIRST in the user's plugins array for that contract to hold.
-    runtime.options.mcp = createMcpSubstrate()
+    // Offered as a service rather than assigned to runtime.options.mcp.
+    //
+    // Tools do not need this at all any more — a plugin registers those
+    // against the engine's registry and this package binds them into each
+    // session. What is left is genuinely MCP's: resources and prompts, which
+    // core deliberately has no vocabulary for.
+    //
+    // A consumer asks core for it from a hook, by which time every factory
+    // has run — which retires the rule this comment used to carry, that the
+    // mcp plugin MUST be FIRST in the user's plugins array. Nothing enforced
+    // that; put it second and the tools silently vanished.
+    const substrate = createMcpSubstrate()
+    provideService('mcp', substrate, { plugin: 'mikser-io-mcp' })
     // mikser_build_report needs the cycle recorded, and recording is off
     // unless a reader asks for it — see report.js requestReport.
     requestReport()
@@ -1546,7 +1587,7 @@ export function mcp(options = {}) {
         // reference (held by plugins, render workers, useLogger
         // consumers) gains the side-channel automatically.
         if (runtime.engine?.logger) {
-            wireLoggerToMcp(runtime.engine.logger, runtime.options.mcp)
+            wireLoggerToMcp(runtime.engine.logger, substrate)
             logger.debug('MCP logger wiring active')
         }
 
@@ -1556,7 +1597,7 @@ export function mcp(options = {}) {
         if (runtime.options.app && runtime.options.mcpPath) {
             await mountMcpOnExpress(
                 runtime.options.app,
-                runtime.options.mcp,
+                substrate,
                 runtime.options.mcpPath,
             )
         }
@@ -1571,7 +1612,7 @@ export function mcp(options = {}) {
     // are silently skipped.
     onLoaded(() => {
         const logger = useLogger()
-        const mcp = runtime.options.mcp
+        const mcp = substrate
         if (!runtime.refs) {
             logger.debug('mikser_refs_* tools skipped: runtime.refs not initialized')
             return
@@ -1976,7 +2017,7 @@ export function mcp(options = {}) {
     })
 
     // mikser_layouts_inspect moved out — registered by mikser-io-layouts
-    // directly against `runtime.options.mcp`, same pattern vector and
+    // directly against the substrate, same pattern vector and
     // schemas use. Domain-owned tools live with the domain plugin; mcp
     // is registry + transport, not a tool catalog.
 
@@ -1998,7 +2039,7 @@ export function mcp(options = {}) {
     //
     onLoaded(() => {
         const logger = useLogger()
-        const mcp = runtime.options.mcp
+        const mcp = substrate
 
         const { render: mcpRender } = useRenderer(runtime, {
             defaultTimeout: options.renderTimeout ?? 30_000,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-mcp",
-  "version": "1.22.0",
+  "version": "2.0.0",
   "description": "MCP (Model Context Protocol) substrate and tools for mikser-io. Extracted from core to iterate on its own release cadence.",
   "main": "index.js",
   "type": "module",
@@ -42,7 +42,7 @@
     "minimatch": "^10.0.3"
   },
   "peerDependencies": {
-    "mikser-io": "^9.53.0",
+    "mikser-io": "^10.0.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/preview.js

@@ -7,7 +7,7 @@
 // the in-memory preview cache.
 //
 // The cache itself lives in mikser-io's preview plugin
-// (runtime.options.preview.{store, get, stats, config}). This module
+// (the `preview` service: {store, get, stats, config}). This module
 // reaches into it via that surface — no cross-plugin imports.
 
 import path from 'node:path'
@@ -15,7 +15,7 @@ import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { randomUUID, createHmac } from 'node:crypto'
 import { z } from 'zod'
-import { useRenderer, mimeForEntity, matchEntity } from 'mikser-io'
+import { useRenderer, mimeForEntity, matchEntity, useService } from 'mikser-io'
 
 // Resolve a path relative to this module's file. Used to find the
 // public/ folder regardless of where the package is installed (works
@@ -122,7 +122,7 @@ const PREVIEW_UI_SHELL_HTML = readFileSync(path.join(__dirname, "public", "previ
 // Plugin function — invoked by mikser-io-mcp/index.js's factory after
 // the substrate is set up. Registers the MCP-UI surface (shell + modes
 // resource + preview_ui + ui_action) AND the preview-render tool (which
-// reaches into runtime.options.preview for the cache).
+// asks core for the preview service).
 //
 // Not a default export plugin in the mikser sense — this is internal
 // composition. The mcp plugin's index.js is what mikser loads; this
@@ -135,15 +135,17 @@ export default ({
     findEntities,
 }) => {
     onLoaded(() => {
-        if (!runtime.options.mcp) return
-        const mcp = runtime.options.mcp
+        // Asked for from a hook, so every factory has run — including this
+        // package's own, which provides it.
+        const mcp = useService('mcp')
+        if (!mcp) return
         const { render: previewRender } = useRenderer(runtime, {
             defaultTimeout: runtime.config.preview?.renderTimeout ?? 30_000,
         })
 
         // mikser_preview_render — render an entity through the pipeline,
         // stash the bytes in the in-memory preview cache (provided by
-        // mikser-io core's preview plugin via runtime.options.preview),
+        // mikser-io core's preview plugin, offered as the `preview` service),
         // and return a clickable URL. Requires --server (or any
         // engine-supplied Express app) so the URL is reachable.
         mcp.simpleTool(
@@ -155,7 +157,7 @@ export default ({
             },
             async ({ entity = {}, options = {} }) => {
                 const logger = useLogger()
-                const preview = runtime.options.preview
+                const preview = useService('preview')
                 const ok = (data) => ({
                     content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
                 })
@@ -176,7 +178,7 @@ export default ({
                         return fail('mikser_preview_render requires either --url <public-url> or --server to be set so the preview URL is reachable. Use mikser_render to get raw bytes inline instead.')
                     }
                     if (!preview) {
-                        return fail('mikser_preview_render requires the preview cache. Ensure mikser-io core is loaded and runtime.options.preview is available.')
+                        return fail('mikser_preview_render requires the preview cache. Ensure the preview plugin from mikser-io core is in your plugins array.')
                     }
 
                     const cfg = preview.config()