@evref-bl/pharo-agent 0.5.3 → 0.5.4

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pharo-agent",
   "displayName": "Pharo Agent",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "private": false,
   "description": "Terminal-first Pharo integration for coding agents.",
   "license": "Apache-2.0",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pharo-agent",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/skills/pharo-setup/SKILL.md

@@ -8,7 +8,7 @@ Run this only when the user asks to enable Pharo tooling in this project.
 From the project root, run the released CLI that matches this plugin:
 
 ```sh
-npx --yes @evref-bl/pharo-agent@0.5.3 init --host claude
+npx --yes @evref-bl/pharo-agent@0.5.4 init --host claude
 ```
 
 Name the host this chat runs in: `--host claude` in Claude Code,

package/src/gateway.js

@@ -6,7 +6,12 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
-import { readJson, readOpenImage, selectRunningImage } from "./runtime.js";
+import {
+  readJson,
+  readOpenImage,
+  selectRunningImage,
+  unappliedPharoMcpPin,
+} from "./runtime.js";
 
 // Read rather than restate: a hard-coded version is one more place for a
 // release to forget, and the host shows this one to the user.
@@ -34,20 +39,33 @@ export async function imageGateway(projectRoot, open) {
   if (!registered.ok) {
     throw new Error(registered.error ?? "Cannot register the PLexus route.");
   }
-  return { gateway, mcpServerId };
+  return { gateway, mcpServerId, image };
+}
+
+// An image whose Pharo MCP predates 2.1.0 resolves tools/call against the
+// advertised list, so a tool it holds but does not advertise answers -32601.
+// That is the loudest way an unapplied pin shows itself, and the message
+// alone sends a reader looking for a tool that is right there.
+const methodNotFound = "-32601";
+
+export function toolFailureMessage(error, image) {
+  const unappliedPin = error.includes(methodNotFound) ? unappliedPharoMcpPin(image) : undefined;
+  return unappliedPin ? `${error}\n${unappliedPin}` : error;
 }
 
 export async function callImageTool(projectRoot, open, toolName, argumentsValue) {
-  const { gateway, mcpServerId } = await imageGateway(projectRoot, open);
+  const { gateway, mcpServerId, image } = await imageGateway(projectRoot, open);
   const result = await gateway.routeToImage({
     mcpServerId,
     toolName,
     arguments: argumentsValue,
   });
-  if (!result.ok) {
-    throw new Error(result.error ?? `Pharo tool ${toolName} failed.`);
+  if (result.ok) {
+    return result.data;
   }
-  return result.data;
+  throw new Error(
+    toolFailureMessage(result.error ?? `Pharo tool ${toolName} failed.`, image),
+  );
 }
 
 export async function listImageTools(projectRoot, open) {

package/src/live.js

@@ -18,6 +18,7 @@ import {
   resolveMountPath,
   selectRunningImage,
   smalltalkString,
+  unappliedPharoMcpPin,
   writeOpenImages,
 } from "./runtime.js";
 
@@ -238,7 +239,14 @@ export async function openAgentImage(projectRoot, imageId) {
     throw error;
   }
   writeOpenImages(projectRoot, { ...openImages, [resolved]: { ...open, projectionPort } });
-  return { imageId: image.id, created, mountPath, projectionPort };
+  const unappliedPin = unappliedPharoMcpPin(image);
+  return {
+    imageId: image.id,
+    created,
+    mountPath,
+    projectionPort,
+    ...(unappliedPin ? { warning: unappliedPin } : {}),
+  };
 }
 
 function unsupportedRunningImage(state, imageId) {

package/src/runtime.js

@@ -131,6 +131,18 @@ export function selectRunningImage(state, imageId) {
   return { image, mcpServerId: image.mcpServers[0].id };
 }
 
+// `mcp.loadPolicy` defaults to ifMissing, so an image that already carries a
+// Pharo MCP keeps it and the version this project pins is never loaded. That
+// is a supported way to run — it is what the policy is for — but nothing said
+// so, and the image's tools then quietly differ from the ones the project was
+// written against. PLexus records it; this says it.
+export function unappliedPharoMcpPin(image) {
+  if (image?.pharoMcpLoad?.state !== "provided") return undefined;
+  return `Image ${image.id} opened with the Pharo MCP it already had, so the version this project pins`
+    + " was not loaded and its tools may differ from the ones this project expects."
+    + " Recreate the image, or set mcp.loadPolicy to always.";
+}
+
 export function smalltalkString(value) {
   return `'${String(value).replaceAll("'", "''")}'`;
 }