@cratis/pi 7.94.0 → 7.96.0

package/README.md

@@ -33,6 +33,20 @@ yields to the managed installation to avoid duplicate resources and hooks. The P
 package manages only Pi; it neither configures other harnesses nor owns a local
 managed corpus.
 
+## MCP servers from the corpus
+
+The packaged `cratis-mcp` extension starts every stdio server declared in
+`mcp-servers.json` whose `profiles` intersect the profiles listed explicitly in
+`.cratis/ai.json` (a profile reached only through another profile's `composes` does
+not start a server; Screenplay keeps its composed selection) (for
+example `codescene` for `cratis/codescene`, `playwright` for `cratis/playwright`).
+Each server gets its own connection, so one failing to start never stops the others,
+and its tools are namespaced by server id (`playwright_browser_navigate`). The
+`command`, `args` and optional literal `env` are used verbatim, without a shell. A
+malformed selected server is skipped with one notice; set
+`mcpServers.<id>.enabled` to `false` in `.cratis/ai.json` to opt a server out.
+`capabilities.json` beside the extension declares this behavior to the Cratis CLI.
+
 ## Screenplay MCP tools
 
 The packaged `cratis-mcp` extension starts the Screenplay MCP server

package/package/corpus/harnesses/pi/extensions/cratis-mcp/CorpusServer.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** A validated stdio server from the corpus descriptor; command, args and env are used verbatim. */
+export interface CorpusServer {
+    id: string;
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+}
+
+/** The servers to start for a project plus the explicit messages for everything skipped. */
+export interface ServerSelection {
+    servers: CorpusServer[];
+    messages: string[];
+}

package/package/corpus/harnesses/pi/extensions/cratis-mcp/ServerBridge.ts

@@ -0,0 +1,113 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { object } from './configuration.ts';
+import type { CorpusServer } from './CorpusServer.ts';
+import { startServer } from './process.ts';
+import { discoverServer, mapServerResult, type ServerCatalog } from './serverProtocol.ts';
+import { selectedCorpusServers } from './servers.ts';
+import type { StdioConnection } from './StdioConnection.ts';
+
+function withDeadline<T>(work: Promise<T>, milliseconds: number, id: string): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const expired = new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`MCP server '${id}' did not become ready within ${milliseconds} ms.`)), milliseconds);
+        timer.unref();
+    });
+    work.catch(() => { /* The deadline already reported the outcome; the disposed connection rejects the abandoned request. */ });
+    return Promise.race([work, expired]).finally(() => clearTimeout(timer));
+}
+
+/** Bridge every selected corpus server except Screenplay: one connection each, isolated failures, tools namespaced by server id. */
+export interface ServerBridge {
+    refresh(context: ExtensionContext, newSession: boolean): Promise<void>;
+    dispose(): void;
+}
+
+export function createServerBridge(pi: ExtensionAPI, corpus: string, connect: (project: string, server: CorpusServer) => StdioConnection = startServer, deadlineMilliseconds = 15_000): ServerBridge {
+    const connections = new Map<string, StdioConnection>();
+    const registered = new Set<string>();
+    const paused = new Set<string>();
+    let selectionKey: string | undefined;
+
+    const notify = (context: ExtensionContext, messages: string[]): void => {
+        if (context.hasUI) messages.forEach(message => context.ui.notify(message, 'warning'));
+    };
+    const deactivate = (): void => {
+        const active = pi.getActiveTools();
+        active.filter(name => registered.has(name)).forEach(name => paused.add(name));
+        if (active.some(name => registered.has(name))) pi.setActiveTools(active.filter(name => !registered.has(name)));
+    };
+    const dispose = (): void => {
+        connections.forEach(connection => connection.dispose());
+        connections.clear();
+        deactivate();
+    };
+    interface Started { server: CorpusServer; connection: StdioConnection; catalog?: ServerCatalog; messages: string[] }
+    /** Connect and discover only; registration happens afterwards in selection order so name claims are deterministic. */
+    const start = async (context: ExtensionContext, server: CorpusServer): Promise<Started> => {
+        const connection = connect(context.cwd, server);
+        connections.set(server.id, connection);
+        try {
+            const catalog = await withDeadline(discoverServer(connection, server.id), deadlineMilliseconds, server.id);
+            if (connections.get(server.id) !== connection || connection.stopped) throw new Error(`MCP server '${server.id}' session ended during discovery.`);
+            return { server, connection, catalog, messages: [...catalog.messages] };
+        } catch (error) {
+            connection.dispose();
+            if (connections.get(server.id) === connection) connections.delete(server.id);
+            return { server, connection, messages: [`MCP server '${server.id}' is unavailable: ${error instanceof Error ? error.message : String(error)}`] };
+        }
+    };
+    const register = ({ server, connection, catalog, messages }: Started, claimed: Set<string>): void => {
+        const existing = new Set(pi.getAllTools().map(tool => tool.name));
+        for (const tool of catalog?.tools ?? []) {
+            if (claimed.has(tool.nativeName) || (existing.has(tool.nativeName) && !registered.has(tool.nativeName))) {
+                messages.push(`MCP server '${server.id}' tool '${tool.name}' was skipped: '${tool.nativeName}' conflicts with another tool.`);
+                continue;
+            }
+            claimed.add(tool.nativeName);
+            pi.registerTool({
+                name: tool.nativeName,
+                label: `${server.id} ${tool.name}`,
+                description: tool.description,
+                parameters: tool.parameters,
+                executionMode: 'sequential',
+                async execute(_toolCallId, parameters, signal) {
+                    if (connections.get(server.id) !== connection || connection.stopped || !pi.getActiveTools().includes(tool.nativeName)) {
+                        throw new Error(`MCP server '${server.id}' is unavailable in this session.`);
+                    }
+                    if (!object(parameters)) throw new Error('MCP arguments must be an object.');
+                    const result = mapServerResult(await connection.request('tools/call', { name: tool.name, arguments: parameters }, signal), server.id);
+                    if (result.details.isError) throw new Error(result.content.map(part => part.type === 'text' ? part.text : '').join('\n') || `MCP server '${server.id}' reported a failed tool call.`);
+                    return result;
+                },
+            });
+        }
+    };
+    const refresh = async (context: ExtensionContext, newSession: boolean): Promise<void> => {
+        let selection: ReturnType<typeof selectedCorpusServers>;
+        try { selection = selectedCorpusServers(context.cwd, corpus); }
+        catch (error) { dispose(); selectionKey = undefined; throw error; }
+        const key = JSON.stringify(selection);
+        if (!newSession && key === selectionKey) return;
+        const previouslyActive = new Set([...pi.getActiveTools(), ...paused]);
+        const oldNames = new Set(registered);
+        dispose();
+        selectionKey = key;
+        const messages = [...selection.messages];
+        const claimed = new Set<string>();
+        // Servers start in parallel; a slow or hung one is abandoned at its own deadline and never delays the others.
+        const outcomes = await Promise.all(selection.servers.map(server => start(context, server)));
+        for (const outcome of outcomes) { register(outcome, claimed); messages.push(...outcome.messages); }
+        claimed.forEach(name => registered.add(name));
+        // Never re-enable a user-disabled tool. SDK allow/exclude restrictions still filter registration.
+        const next = pi.getActiveTools().filter(name => !registered.has(name) || (claimed.has(name) && (!oldNames.has(name) || previouslyActive.has(name))));
+        for (const name of claimed) if (oldNames.has(name) && previouslyActive.has(name)) next.push(name);
+        pi.setActiveTools([...new Set(next)]);
+        paused.clear();
+        notify(context, messages);
+    };
+
+    return { refresh, dispose: () => { dispose(); selectionKey = undefined; } };
+}

package/package/corpus/harnesses/pi/extensions/cratis-mcp/StdioConnection.ts

@@ -15,7 +15,7 @@ export class StdioConnection {
     private _termination?: ReturnType<typeof setTimeout>;
     private readonly _maximumBytes = 8 * 1024 * 1024;
 
-    constructor(private readonly _child: ChildProcessWithoutNullStreams, private readonly _timeout = 30_000) {
+    constructor(private readonly _child: ChildProcessWithoutNullStreams, private readonly _timeout = 30_000, private readonly _label = 'Screenplay', private readonly _tolerant = false) {
         _child.stdout.on('data', this.receive);
         _child.stdout.on('end', this.ended);
         _child.stdout.on('error', this.streamFailed);
@@ -32,22 +32,22 @@ export class StdioConnection {
 
     async request(method: string, params: Record<string, unknown>, signal?: AbortSignal, mutation = false): Promise<unknown> {
         if (this._failure) throw this._failure;
-        if (signal?.aborted) throw new ConnectionFailure('Screenplay request cancelled before sending.');
-        if (this._pending) throw new ConnectionFailure('Screenplay is busy; parallel requests are not queued.');
+        if (signal?.aborted) throw new ConnectionFailure(`${this._label} request cancelled before sending.`);
+        if (this._pending) throw new ConnectionFailure(`${this._label} is busy; parallel requests are not queued.`);
         const id = ++this._sequence;
         const line = this.encode({ jsonrpc: '2.0', id, method, params });
         return new Promise((resolve, reject) => {
-            const abort = () => this.stop('Screenplay request cancelled after sending.');
-            const timer = setTimeout(() => this.stop('Screenplay request timed out.'), this._timeout);
+            const abort = () => this.stop(`${this._label} request cancelled after sending.`);
+            const timer = setTimeout(() => this.stop(`${this._label} request timed out.`), this._timeout);
             this._pending = {
                 id, mutation, resolve, reject,
                 cleanup: () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); },
             };
             signal?.addEventListener('abort', abort, { once: true });
             try {
-                this._child.stdin.write(line, error => { if (error) this.stop('Screenplay input pipe failed.'); });
+                this._child.stdin.write(line, error => { if (error) this.stop(`${this._label} input pipe failed.`); });
             } catch {
-                this.stop('Screenplay input pipe failed.');
+                this.stop(`${this._label} input pipe failed.`);
             }
         });
     }
@@ -55,18 +55,18 @@ export class StdioConnection {
     notify(method: string): void {
         if (this._failure) throw this._failure;
         try {
-            this._child.stdin.write(this.encode({ jsonrpc: '2.0', method }), error => { if (error) this.stop('Screenplay notification failed.'); });
+            this._child.stdin.write(this.encode({ jsonrpc: '2.0', method }), error => { if (error) this.stop(`${this._label} notification failed.`); });
         } catch {
-            this.stop('Screenplay notification failed.');
+            this.stop(`${this._label} notification failed.`);
             throw this._failure;
         }
     }
 
-    dispose(): void { this.stop('Screenplay session closed.'); }
+    dispose(): void { this.stop(`${this._label} session closed.`); }
 
     private encode(value: unknown): string {
         const line = `${JSON.stringify(value)}\n`;
-        if (Buffer.byteLength(line) > this._maximumBytes) throw new ConnectionFailure('Screenplay request exceeds the 8 MiB transport limit.');
+        if (Buffer.byteLength(line) > this._maximumBytes) throw new ConnectionFailure(`${this._label} request exceeds the 8 MiB transport limit.`);
         return line;
     }
 
@@ -82,7 +82,7 @@ export class StdioConnection {
                 this._buffer = Buffer.alloc(0);
                 this.accept(line);
             } catch {
-                this.stop('Screenplay returned invalid UTF-8 protocol data.');
+                this.stop(`${this._label} returned invalid UTF-8 protocol data.`);
             }
             if (this.stopped) return;
             start = index + 1;
@@ -92,7 +92,7 @@ export class StdioConnection {
 
     private append(chunk: Buffer): boolean {
         if (this._buffer.length + chunk.length > this._maximumBytes) {
-            this.stop('Screenplay response exceeds the 8 MiB transport limit.');
+            this.stop(`${this._label} response exceeds the 8 MiB transport limit.`);
             return false;
         }
         this._buffer = Buffer.concat([this._buffer, chunk]);
@@ -103,6 +103,13 @@ export class StdioConnection {
         try {
             const message: unknown = JSON.parse(line);
             if (!object(message) || message.jsonrpc !== '2.0') throw new Error();
+            if ('method' in message && this._tolerant) {
+                // Third-party servers may notify or ask; this client offers no capabilities, so refuse requests and ignore notifications.
+                if ('id' in message && typeof message.method === 'string') {
+                    this._child.stdin.write(this.encode({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'Method not found' } }));
+                }
+                return;
+            }
             if ('method' in message) {
                 // This pinned server does not send requests or changing tool lists.
                 throw new Error();
@@ -113,14 +120,14 @@ export class StdioConnection {
             this._pending = undefined;
             pending.cleanup();
             if (object(message.error)) {
-                pending.reject(new ConnectionFailure(`Screenplay protocol error ${message.error.code}: ${message.error.message}`, pending.mutation));
+                pending.reject(new ConnectionFailure(`${this._label} protocol error ${message.error.code}: ${message.error.message}`, pending.mutation));
                 // A server failure during mutation is not evidence that nothing was written.
-                if (pending.mutation) this.stop('Screenplay mutation failed with a protocol error.', true);
+                if (pending.mutation) this.stop(`${this._label} mutation failed with a protocol error.`, true);
             } else {
                 pending.resolve(message.result);
             }
         } catch {
-            this.stop('Screenplay returned malformed or unexpected JSON-RPC.');
+            this.stop(`${this._label} returned malformed or unexpected JSON-RPC.`);
         }
     }
 
@@ -145,11 +152,13 @@ export class StdioConnection {
     }
 
     private readonly drain = (): void => { /* Drain server stderr without exposing it as a protocol result. */ };
-    private readonly ended = (): void => this.stop('Screenplay output closed before session shutdown.');
-    private readonly streamFailed = (): void => this.stop('Screenplay stdio failed.');
-    private readonly spawnFailed = (): void => this.stop('Cannot launch native cratis screenplay mcp. Install/update the Cratis CLI through its normal channel; this extension never downloads a runtime.');
+    private readonly ended = (): void => this.stop(`${this._label} output closed before session shutdown.`);
+    private readonly streamFailed = (): void => this.stop(`${this._label} stdio failed.`);
+    private readonly spawnFailed = (): void => this.stop(this._label !== 'Screenplay'
+        ? `Cannot launch the ${this._label} MCP server command. Check that it is installed; this extension never downloads a runtime.`
+        : 'Cannot launch native cratis screenplay mcp. Install/update the Cratis CLI through its normal channel; this extension never downloads a runtime.');
     private readonly closed = (): void => {
-        this.stop('Screenplay process exited. Check that the installed Cratis CLI includes the embedded Screenplay runtime; no runtime is downloaded by this extension.');
+        this.stop(this._label !== 'Screenplay' ? `${this._label} process exited.` : 'Screenplay process exited. Check that the installed Cratis CLI includes the embedded Screenplay runtime; no runtime is downloaded by this extension.');
         clearTimeout(this._termination);
         this._child.stdout.removeListener('error', this.streamFailed);
         this._child.stdin.removeListener('error', this.streamFailed);

package/package/corpus/harnesses/pi/extensions/cratis-mcp/capabilities.json

@@ -0,0 +1 @@
+{ "servers": "selected-profiles" }

package/package/corpus/harnesses/pi/extensions/cratis-mcp/configuration.ts

@@ -8,7 +8,7 @@ export function object(value: unknown): value is Record<string, unknown> {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
-function readJson(path: string): Record<string, unknown> {
+export function readJson(path: string): Record<string, unknown> {
     if (lstatSync(path).size > 1024 * 1024) throw new Error(`Cratis configuration is too large: ${path}`);
     const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
     if (!object(value)) throw new Error(`Expected a JSON object: ${path}`);
@@ -21,6 +21,10 @@ function strings(value: unknown): string[] {
     return value;
 }
 
+export function supportedSchema(version: unknown): boolean {
+    return typeof version === 'string' && /^1\.\d+$/.test(version);
+}
+
 /** Resolve through existing directories only, refusing every source-root symlink. Never creates a directory. */
 export function physicalRoot(project: string, root: string): string {
     if (!root || isAbsolute(root) || root.includes('\0')) throw new Error('Screenplay root must be a nonempty project-relative directory.');
@@ -45,8 +49,16 @@ export function physicalRoot(project: string, root: string): string {
     return current;
 }
 
-/** Select only the shipped Screenplay descriptor, never project-supplied commands or environments. */
-export function selectedServer(project: string, corpus: string) {
+export interface ProfileResolution {
+    configuration: Record<string, unknown>;
+    selected: Set<string>;
+    /** Profiles listed directly in `.cratis/ai.json`, before any `composes` expansion. */
+    explicit: Set<string>;
+    nonApplicationSelection: boolean;
+}
+
+/** Resolve the selected profiles (after `composes` expansion) from the project's `.cratis/ai.json`. */
+export function resolveProfiles(project: string, corpus: string): ProfileResolution | undefined {
     let configuration: Record<string, unknown>;
     try {
         configuration = readJson(join(project, '.cratis', 'ai.json'));
@@ -86,7 +98,14 @@ export function selectedServer(project: string, corpus: string) {
         strings(profile.composes).forEach(child => select(child, false, applicationPath));
     };
     requested.forEach(id => select(id, true));
-    if (!selected.has('cratis/screenplay')) return undefined;
+    return { configuration, selected, explicit: new Set(requested), nonApplicationSelection };
+}
+
+/** Select only the shipped Screenplay descriptor, never project-supplied commands or environments. */
+export function selectedServer(project: string, corpus: string) {
+    const resolution = resolveProfiles(project, corpus);
+    if (!resolution?.selected.has('cratis/screenplay')) return undefined;
+    const { configuration, nonApplicationSelection } = resolution;
     const overrides = configuration.mcpServers;
     if (overrides !== undefined && !object(overrides)) throw new Error('Invalid mcpServers configuration.');
     const screenplay = object(overrides) ? overrides.screenplay : undefined;
@@ -94,7 +113,9 @@ export function selectedServer(project: string, corpus: string) {
     if (object(screenplay) && screenplay.enabled === false) return undefined;
     if (object(screenplay) && screenplay.enabled !== undefined && screenplay.enabled !== true) throw new Error('Screenplay MCP enabled must be a boolean.');
     const descriptor = readJson(join(corpus, 'mcp-servers.json'));
-    if (descriptor.schemaVersion !== '1.0' || !Array.isArray(descriptor.servers)) throw new Error('Unsupported Cratis MCP descriptor.');
+    // Any 1.x descriptor is accepted; another major loads no corpus MCP servers (the generic bridge reports it once).
+    if (!supportedSchema(descriptor.schemaVersion)) return undefined;
+    if (!Array.isArray(descriptor.servers)) throw new Error('Unsupported Cratis MCP descriptor.');
     const servers = descriptor.servers.filter(server => object(server) && server.id === 'screenplay');
     if (servers.length !== 1 || !object(servers[0])) throw new Error('Expected exactly one Screenplay MCP descriptor.');
     const server = servers[0];

package/package/corpus/harnesses/pi/extensions/cratis-mcp/index.ts

@@ -7,8 +7,10 @@ import { fileURLToPath } from 'node:url';
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { ConnectionFailure } from './ConnectionFailure.ts';
 import { object, selectedServer } from './configuration.ts';
-import { startConnection, supportsNoModelStartup } from './process.ts';
+import type { CorpusServer } from './CorpusServer.ts';
+import { startConnection, startServer, supportsNoModelStartup } from './process.ts';
 import { discover, failedResult, mapResult } from './protocol.ts';
+import { createServerBridge } from './ServerBridge.ts';
 import type { DiscoveredTool } from './DiscoveredTool.ts';
 import type { StdioConnection } from './StdioConnection.ts';
 
@@ -16,7 +18,8 @@ const extensionDirectory = dirname(fileURLToPath(import.meta.url));
 const bundledCorpus = resolve(extensionDirectory, '..', '..', '..', '..');
 
 /** Native tools go through Pi's tool_call restrictions and normal execution/result pipeline. */
-export function registerBridge(pi: ExtensionAPI, corpus: string, connect = startConnection, checkVersion = supportsNoModelStartup): void {
+export function registerBridge(pi: ExtensionAPI, corpus: string, connect = startConnection, checkVersion = supportsNoModelStartup, connectServer: (project: string, server: CorpusServer) => StdioConnection = startServer): void {
+    const servers = createServerBridge(pi, corpus, connectServer);
     let connection: StdioConnection | undefined;
     let selectionKey: string | undefined;
     let attempted = false;
@@ -149,9 +152,15 @@ export function registerBridge(pi: ExtensionAPI, corpus: string, connect = start
         }
     };
 
-    pi.on('session_start', (_event, context) => refresh(context, true));
-    pi.on('before_agent_start', async (_event, context) => { await refresh(context); });
-    pi.on('session_shutdown', () => { dispose(); failures.clear(); });
+    // Screenplay and the other corpus servers fail independently; the first failure is surfaced after both ran.
+    const refreshAll = async (context: ExtensionContext, newSession: boolean): Promise<void> => {
+        const outcomes = await Promise.allSettled([refresh(context, newSession), servers.refresh(context, newSession)]);
+        const failed = outcomes.find(outcome => outcome.status === 'rejected');
+        if (failed) throw failed.reason;
+    };
+    pi.on('session_start', (_event, context) => refreshAll(context, true));
+    pi.on('before_agent_start', async (_event, context) => { await refreshAll(context, false); });
+    pi.on('session_shutdown', () => { dispose(); servers.dispose(); failures.clear(); });
     pi.on('tool_result', event => {
         if (!registered.has(event.toolName)) return;
         const failure = failures.get(event.toolCallId);

package/package/corpus/harnesses/pi/extensions/cratis-mcp/process.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { execFile, spawn } from 'node:child_process';
+import type { CorpusServer } from './CorpusServer.ts';
 import { StdioConnection } from './StdioConnection.ts';
 
 /** Preserve OS/runtime lookup only; never copy arbitrary credentials or descriptor environment values. */
@@ -43,3 +44,14 @@ export function startConnection(project: string, launch: typeof spawn = spawn):
         windowsHide: true,
     }));
 }
+
+/** Launch a corpus server verbatim (no shell, no interpolation): the default environment plus its declared literal env only. */
+export function startServer(project: string, server: CorpusServer, launch: typeof spawn = spawn): StdioConnection {
+    return new StdioConnection(launch(server.command, server.args, {
+        cwd: project,
+        env: { ...childEnvironment(), ...server.env },
+        shell: false,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+    }), 30_000, server.id, true);
+}

package/package/corpus/harnesses/pi/extensions/cratis-mcp/serverProtocol.ts

@@ -0,0 +1,92 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { TSchema } from 'typebox';
+import { object } from './configuration.ts';
+import type { StdioConnection } from './StdioConnection.ts';
+
+/** A tool of a corpus server other than Screenplay, exposed under a name namespaced by the server id. */
+export interface ServerTool {
+    name: string;
+    nativeName: string;
+    description: string;
+    parameters: TSchema;
+}
+
+export interface ServerCatalog {
+    tools: ServerTool[];
+    messages: string[];
+}
+
+const maximumTools = 128;
+const maximumPages = 8;
+const maximumNativeNameLength = 64;
+const maximumDescriptionLength = 4 * 1024;
+const maximumSchemaLength = 64 * 1024;
+const maximumImageLength = 2 * 1024 * 1024;
+const imageTypes = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+
+/** Initialize and list tools; tools that cannot be exposed safely are skipped with a message rather than failing the server. */
+export async function discoverServer(connection: StdioConnection, id: string): Promise<ServerCatalog> {
+    const initialized = await connection.request('initialize', {
+        protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'cratis.pi', version: '1.0.0' },
+    });
+    if (!object(initialized) || !object(initialized.capabilities) || !object(initialized.capabilities.tools)) {
+        throw new Error(`MCP server '${id}' did not advertise tool support.`);
+    }
+    connection.notify('notifications/initialized');
+    const listed: unknown[] = [];
+    let cursor: unknown;
+    for (let page = 0; page < maximumPages; page++) {
+        const response = await connection.request('tools/list', cursor === undefined ? {} : { cursor });
+        if (!object(response) || !Array.isArray(response.tools)) throw new Error(`MCP server '${id}' returned an invalid tool list.`);
+        listed.push(...response.tools);
+        if (listed.length > maximumTools) throw new Error(`MCP server '${id}' exposes more than ${maximumTools} tools.`);
+        cursor = response.nextCursor;
+        if (cursor === undefined) break;
+        if (typeof cursor !== 'string') throw new Error(`MCP server '${id}' returned an invalid pagination cursor.`);
+    }
+    const catalog: ServerCatalog = { tools: [], messages: [] };
+    const names = new Set<string>();
+    for (const tool of listed) {
+        const name = object(tool) ? tool.name : undefined;
+        if (!object(tool) || typeof name !== 'string' || !name || !object(tool.inputSchema) || tool.inputSchema.type !== 'object' ||
+            (tool.description !== undefined && typeof tool.description !== 'string')) {
+            catalog.messages.push(`MCP server '${id}' has a tool with an invalid name or input schema; it was skipped.`);
+            continue;
+        }
+        if (JSON.stringify(tool.inputSchema).length > maximumSchemaLength || ((tool.description as string | undefined)?.length ?? 0) > maximumDescriptionLength) {
+            catalog.messages.push(`MCP server '${id}' tool '${name}' was skipped: its description or input schema is too large.`);
+            continue;
+        }
+        const nativeName = `${id}_${name.replace(/[^A-Za-z0-9_]/g, '_')}`;
+        if (nativeName.length > maximumNativeNameLength || names.has(nativeName)) {
+            catalog.messages.push(`MCP server '${id}' tool '${name}' was skipped: its namespaced name is too long or not unique.`);
+            continue;
+        }
+        names.add(nativeName);
+        catalog.tools.push({ name, nativeName, description: (tool.description as string | undefined) ?? '', parameters: tool.inputSchema as TSchema });
+    }
+    if (!catalog.tools.length) throw new Error(`MCP server '${id}' exposes no usable tools.`);
+    return catalog;
+}
+
+/** Map an MCP result to Pi content. Server-reported errors throw so Pi marks the call failed. */
+export function mapServerResult(result: unknown, id: string) {
+    if (!object(result) || !Array.isArray(result.content) || (result.isError !== undefined && typeof result.isError !== 'boolean')) {
+        throw new Error(`Malformed MCP result from '${id}'.`);
+    }
+    const content = result.content.map((part: unknown) => {
+        if (object(part) && part.type === 'text' && typeof part.text === 'string') return { type: 'text' as const, text: part.text };
+        if (object(part) && part.type === 'image' && typeof part.data === 'string' && typeof part.mimeType === 'string') {
+            if (!imageTypes.has(part.mimeType) || part.data.length > maximumImageLength) return { type: 'text' as const, text: `[image omitted: unsupported type or larger than ${maximumImageLength / 1024 / 1024} MiB]` };
+            return { type: 'image' as const, data: part.data, mimeType: part.mimeType };
+        }
+        return { type: 'text' as const, text: `[unsupported ${object(part) ? String(part.type) : 'unknown'} content omitted]` };
+    });
+    const maximumCharacters = 32 * 1024;
+    const bounded = content.map(part => part.type === 'text' && part.text.length > maximumCharacters
+        ? { ...part, text: `${part.text.slice(0, maximumCharacters)}\n[display truncated]` }
+        : part);
+    return { content: bounded, details: { isError: result.isError === true, structuredContent: result.structuredContent } };
+}

package/package/corpus/harnesses/pi/extensions/cratis-mcp/servers.ts

@@ -0,0 +1,76 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { join } from 'node:path';
+import { object, readJson, resolveProfiles, supportedSchema } from './configuration.ts';
+import type { CorpusServer, ServerSelection } from './CorpusServer.ts';
+
+const validId = /^[A-Za-z0-9_-]+$/;
+
+function isSelected(entry: Record<string, unknown>, selected: Set<string>): boolean {
+    return Array.isArray(entry.profiles) && entry.profiles.some(profile => typeof profile === 'string' && selected.has(profile));
+}
+
+function problem(entry: Record<string, unknown>): string | undefined {
+    if (typeof entry.id !== 'string' || !validId.test(entry.id)) return 'the id must match ^[A-Za-z0-9_-]+$';
+    if (entry.transport !== 'stdio') return 'only the stdio transport is supported';
+    if (typeof entry.command !== 'string' || !entry.command) return 'the command is missing or empty';
+    if (!Array.isArray(entry.args) || !entry.args.every(argument => typeof argument === 'string')) return 'args must be an array of strings';
+    if (entry.env !== undefined && (!object(entry.env) || !Object.values(entry.env).every(value => typeof value === 'string'))) {
+        return 'env must be an object of literal string values';
+    }
+    return undefined;
+}
+
+/** `mcpServers.<id>.enabled`: false opts out, a non-boolean is an error for that server only. */
+function optOut(overrides: Record<string, unknown>, id: string): 'enabled' | 'disabled' | string {
+    const override = overrides[id];
+    if (override === undefined) return 'enabled';
+    if (!object(override)) return 'the mcpServers configuration must be an object';
+    if (override.enabled === undefined || override.enabled === true) return 'enabled';
+    return override.enabled === false ? 'disabled' : 'mcpServers enabled must be a boolean';
+}
+
+/** Select every stdio server whose profiles intersect the explicitly listed profiles (never composed ones), except Screenplay which keeps its own path. */
+export function selectedCorpusServers(project: string, corpus: string): ServerSelection {
+    const selection: ServerSelection = { servers: [], messages: [] };
+    const resolution = resolveProfiles(project, corpus);
+    if (!resolution) return selection;
+    const descriptor = readJson(join(corpus, 'mcp-servers.json'));
+    if (!supportedSchema(descriptor.schemaVersion)) {
+        selection.messages.push(`Cratis MCP descriptor schemaVersion '${String(descriptor.schemaVersion)}' is not supported; no corpus MCP servers were loaded.`);
+        return selection;
+    }
+    if (!Array.isArray(descriptor.servers)) {
+        selection.messages.push('Cratis MCP descriptor has no servers list; no corpus MCP servers were loaded.');
+        return selection;
+    }
+    const overrides = resolution.configuration.mcpServers;
+    if (overrides !== undefined && !object(overrides)) {
+        selection.messages.push('Invalid mcpServers configuration; no corpus MCP servers were loaded.');
+        return selection;
+    }
+    const entries = descriptor.servers.filter(object);
+    const counts = new Map<unknown, number>();
+    entries.forEach(entry => counts.set(entry.id, (counts.get(entry.id) ?? 0) + 1));
+    const reported = new Set<unknown>();
+    for (const entry of entries) {
+        if (entry.id === 'screenplay') continue;
+        // An entry without profiles can never be selected, so it is ignored like any other unselected entry.
+        if (!isSelected(entry, resolution.explicit)) continue;
+        const label = `MCP server '${String(entry.id)}'`;
+        if (counts.get(entry.id)! > 1) {
+            if (!reported.has(entry.id)) selection.messages.push(`${label} was skipped: the descriptor declares the id more than once.`);
+            reported.add(entry.id);
+            continue;
+        }
+        const invalid = problem(entry);
+        if (invalid) { selection.messages.push(`${label} was skipped: ${invalid}.`); continue; }
+        const id = entry.id as string;
+        const state = object(overrides) ? optOut(overrides, id) : 'enabled';
+        if (state === 'disabled') continue;
+        if (state !== 'enabled') { selection.messages.push(`${label} was skipped: ${state}.`); continue; }
+        selection.servers.push({ id, command: entry.command as string, args: entry.args as string[], env: { ...(entry.env as Record<string, string> | undefined) } });
+    }
+    return selection;
+}

package/package/corpus/skills/cratis-chronicle-cli-operations/SKILL.md

@@ -247,6 +247,10 @@ store gets replayed. A failed partition you have not yet explained is not a
 thing to clear: read it, fix the handler, then replay. Clearing it first
 destroys the evidence and the same failure returns on the next event.
 
+## Compare a namespace with its model
+
+`cratis screenplay conform-namespace` is read-only and sits outside the `chronicle` group and its guard: it reads the registry, observers and event metadata of one namespace and compares them with a `.play` model. Use it for a post-deploy check; the procedure and exit codes are in `cratis-screenplay-render-and-gap-fill` [post-deploy check](../cratis-screenplay-render-and-gap-fill/references/post-deploy-check.md). Its exit `4` is a refused read: obtain a context with read access, never widen permissions.
+
 ## What the CLI cannot do
 
 There is no `delete`, `purge`, `redact`, or `revise` command. Event redaction

package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/SKILL.md

@@ -205,6 +205,7 @@ Read [references/neighbouring-skills.md](references/neighbouring-skills.md) when
 - `references/renderability-gate.md` - classify the probe's codes, estimate the blast radius.
 - `references/delivery-protocol.md` - inputs, commands, reading results, `Customizations/`.
 - `references/gap-fill-handoff.md` - the brief for `slice-implementer`, fallback record flow.
+- `references/post-deploy-check.md` - after deployment, compare the model with a running namespace using `cratis screenplay conform-namespace`; read-only, with its exit codes.
 - `references/drift-and-fallback-record.md` - drift, publication refusals, the fallback record, code changed since verification.
 - Read `references/hand-written-changes.md` when investigating hand-written changes against the contract; it defines finding kinds, resolution routing and the report.
 - Read `references/worked-example.md` when preparing the classification and report for a refused render; it contains a complete model.

package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/references/post-deploy-check.md

@@ -0,0 +1,57 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Post-deploy check: does the running namespace match the model
+
+After a render is delivered and deployed, `cratis screenplay conform-namespace` compares the
+compiled model with what one running Chronicle namespace holds. Render verification and
+`conform` never see the running store; this check does. How to read its verdict is in the
+toolchain's [observation comparison](../../cratis-screenplay-toolchain/references/observation-comparison.md),
+including the CLI version it needs.
+
+## Run it
+
+```bash
+cratis screenplay conform-namespace <model-root> --event-store <store> --namespace <namespace> -o json-compact
+```
+
+- Pass the model root (the root `.play` file or the folder of one application), never a single
+  fragment of a folder.
+- Name the event store and namespace explicitly. The built-in default is never assumed, and a
+  name differing only in case is reported, not chosen for you.
+- `--sequence` selects another sequence (default `event-log`); `--from`, `--to` and `--max-events`
+  bound the scan (default `100000` events, up to the tail captured at the start).
+- Add `--fail-on-drift` in a pipeline so the exit code carries the verdict.
+
+## Authorization and effect
+
+The command is read-only: it never replays observers, appends events or changes the model, and
+it is not a `chronicle` command, so the Chronicle mutation guard does not apply. It still needs a
+connection to the target server with permission to read the event type registry, observers and
+event metadata. Use the context the user named; resolve it as in `cratis-chronicle-cli-operations`.
+Do not log in, switch contexts or point at another environment to make it work. A production
+namespace is checked only when the request named it.
+
+## Act on the result
+
+| Exit | Meaning | Act |
+| --- | --- | --- |
+| `0` | The comparison ran | Read `hasDrift` and the findings; drift alone does not fail without `--fail-on-drift` |
+| `7` | Known drift (with `--fail-on-drift`) | Triage each Drift finding: fix the model through the model workflow, or fix the deployment; never edit a rendered file to silence it |
+| `8` | Inconclusive (with `--fail-on-drift`), or the scan was interrupted | Report inconclusive; widen coverage or wait for lagging reactors, then rerun once |
+| `5` | Model errors, missing store, namespace or sequence, invalid bounds | Fix the input; nothing was compared |
+| `2` | Server unreachable | Report the connection failure; do not retry through another route |
+| `3` | Chronicle refused or failed a read | Report it; no snapshot was built |
+| `4` | Authorization missing for a read | Ask the user for a context with read access; do not widen permissions yourself |
+
+Exit `4` for a refused read and exit `8` for an interrupted scan require Cratis CLI 3.89.1 or later
+(`cratis --version`). On an older CLI, treat any exit other than `0` and `7` as "not compared".
+
+A failed read is never an empty store.
+
+## Report
+
+Record the verdict next to the deployment: model identity, event store, namespace, sequence,
+examined range against the captured tail, `Complete`, Drift findings and Unknown reasons. A
+partial or inconclusive result is reported as such, never as a pass. Remediation that changes
+the model or code returns to the render and gap-fill procedure.

package/package/corpus/skills/cratis-screenplay-toolchain/SKILL.md

@@ -65,7 +65,7 @@ superseded statement needs context; exceptions do not change the contract.
 | | Standalone `screenplay` | `cratis screenplay ...` |
 | --- | --- | --- |
 | Check root | `screenplay <root> --warnaserror --no-color` | `cratis screenplay validate <root> --warnings-as-errors -o json-compact` |
-| Scope/checks | `--scope <address>`, `--check <names>`; a scoped pass is not whole-application success | `validate --executable` (bundled binder, no write), `--check <names>`, `--scope`; `render --scope`/`--check`; `cratis screenplay conform` |
+| Scope/checks | `--scope <address>`, `--check <names>`; a scoped pass is not whole-application success | `validate --executable` (bundled binder, no write), `--check <names>`, `--scope`; `render --scope`/`--check`; `cratis screenplay conform`, `cratis screenplay conform-namespace` |
 | Declared gate | `screenplay <root> --print-gate`, `--format json`, `--no-gate-file` | `validate <root> --print-gate`, `--no-gate-file`; the same `screenplay.json` |
 | Reference execution | `screenplay test <root>` or MCP `run-specifications` | Discover bundled MCP capability; target tests are not V4 |
 | MCP | `screenplay mcp <root>`; discover schemas | `cratis screenplay mcp [root]`; registered by `cratis ai install` |
@@ -96,6 +96,8 @@ for MCP initialization, source identity and reporting. Without MCP, report
 version, source identity and any blocking codes; MCP `modelRevision` is semantic,
 not the source identity.
 
+Read [observation comparison](references/observation-comparison.md) when asking whether a running namespace holds what the model declares, or when reading a `conform-namespace` verdict. It differs from model comparison (model versus model) and `conform` (model versus code).
+
 ## Subsets (write from the one your mode needs)
 
 - **Design**: every construct family parses; use it to model first. Compiled shapes:

package/package/corpus/skills/cratis-screenplay-toolchain/references/observation-comparison.md

@@ -0,0 +1,83 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Observation comparison: model versus running store
+
+Requires Cratis CLI 3.85.0 or later (`cratis --version`) for `cratis screenplay conform-namespace`, and
+3.89.1 or later for the refused-read exit `4` and clean Ctrl+C handling described below; older CLIs lack
+the verb. Without it, report "observation comparison not run" and do not substitute `conform`.
+
+## Three comparisons, three questions
+
+| Comparison | Compares | Answers | Does not answer |
+| --- | --- | --- | --- |
+| Model comparison (`semantic-diff`) | two authored models | what changed between revisions | whether anything runs |
+| `cratis screenplay conform` | a model with source code | whether hand-written code realizes the slice | whether the deployed system did it |
+| Observation comparison (`cratis screenplay conform-namespace`) | a compiled model with a bounded snapshot of one running Chronicle namespace | do the observed event relationships agree with the model | payload agreement, behavior, specifications passing |
+
+Reach for observation comparison after a deploy, or when a namespace may have diverged from the
+model: are the declared event types registered, were undeclared events appended, did each command
+and reactor append what the model says it produces, and are the declared reactions subscribed.
+It reads event metadata only, never payloads, event source ids or command values.
+
+## Read the verdict
+
+The host reports three verdict values and a separate completeness flag.
+
+| `HasDrift` | Meaning | Action |
+| --- | --- | --- |
+| true | Known drift exists, even if other evidence is incomplete | Triage each Drift finding |
+| false | The comparison was complete and found no drift | Report no drift, with the scope |
+| null (omitted in JSON, `inconclusive` in human output) | Drift is neither established nor ruled out | Report inconclusive; never turn it into "no drift" |
+
+`Complete` is true only when the scan covered the sequence fully **and** no finding is Unknown.
+A report can have `HasDrift` true and `Complete` false.
+
+## Finding outcomes
+
+| Outcome | Reading |
+| --- | --- |
+| Drift | The store disagrees with the model on something the evidence establishes |
+| Informational | A difference that is not a contradiction, such as a declared event that has not yet been appended |
+| Unknown | The evidence cannot establish agreement or disagreement; the reason says why |
+| Excluded | Outside this application, such as a foreign event or a platform consumer |
+
+Typical Drift: a declared event type missing from the registry, an undeclared event appended,
+an undeclared generation, a mapped producer appending outside its declared productions, or a
+declared reaction with no subscription.
+
+## Unknown reasons
+
+| Reason | What to do |
+| --- | --- |
+| `PartialCoverage` | Widen the range (`--from`, `--to`, `--max-events`) and rerun |
+| `UnattributedEvents` | Events without a command or reactor in their causation; the producer cannot be judged |
+| `UnmappedProducer`, `UnmappedConstruct`, `AmbiguousIdentity` | The model name did not map to exactly one observed identity; do not guess one |
+| `OpaqueReaction`, `ConditionalProduction`, `DescribedHandler`, `NonEventTrigger` | The model does not state the production unconditionally, so absence proves nothing |
+| `ConsumerBehind` | The reactor has not reached the tail; wait for it and rerun |
+| `ConsumerKindNotCompared` | Projections and reducers are not compared; their subscriptions are never evidence either way |
+
+## Pitfalls
+
+- "No matching appends within coverage" does not mean the command or reactor never ran. It is
+  Informational: no attributed event shows that it ran inside the examined range.
+- Scanned absence under partial coverage is Unknown, never drift. Registry checks are the
+  exception: the event-type registry is read in full, so a declared event that is not registered
+  (`EventNotRegistered`) is drift whatever the coverage. A missing production is drift only
+  with full coverage, an unambiguous producer mapping, another event attributed to that producer,
+  and no unattributed appends of the expected type.
+- Presence is stronger than absence: an undeclared event that was appended is drift even under
+  partial coverage.
+- A clean result proves only the relationships it checked. Read the report's not-established
+  statements; they list the limits.
+- Event generations are approximated: each appended event counts against the highest registered
+  generation of its type.
+- One sequence is compared per run, `event-log` by default.
+
+## Report it
+
+State the verdict value, `Complete`, the event store, namespace and sequence, the examined range
+against the captured tail, each Drift finding with its statement, and each Unknown reason. The
+post-deploy procedure and its exit codes are in
+[post-deploy check](../../cratis-screenplay-render-and-gap-fill/references/post-deploy-check.md).
+Run the comparison through the CLI; no MCP tool offers it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.94.0",
+  "version": "7.96.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [