@evref-bl/pharo-agent 0.5.3 → 0.5.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pharo-agent",
   "displayName": "Pharo Agent",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "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.5",
   "private": false,
   "description": "Terminal-first Pharo integration for coding agents.",
   "license": "Apache-2.0",
@@ -31,9 +31,9 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@evref-bl/pharo-mcp": "2.1.0",
-    "@evref-bl/plexus": "0.5.4",
-    "@evref-bl/plexus-gateway": "0.5.4",
+    "@evref-bl/pharo-mcp": "2.1.1",
+    "@evref-bl/plexus": "0.5.5",
+    "@evref-bl/plexus-gateway": "0.5.5",
     "@modelcontextprotocol/sdk": "1.32.1"
   }
 }

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.5",
   "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.5 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

@@ -12,16 +12,18 @@ import { callImageTool } from "./gateway.js";
 import { readProjectConfig, writeProjectConfig } from "./project.js";
 import {
   defaultImageId,
+  openedImageIsAlive,
   readConfig,
   readOpenImages,
   resolveImageId,
   resolveMountPath,
   selectRunningImage,
   smalltalkString,
+  unappliedPharoMcpPin,
   writeOpenImages,
 } from "./runtime.js";
 
-export const pifsRelease = "v0.6.1";
+export const pifsRelease = "v0.6.2";
 
 // The class-side PIFSServer messages this plugin sends into the image. The
 // release automation checks that a published PIFS still implements them: a pin
@@ -185,9 +187,18 @@ export function fetchPifsRelease(cloneDirectory, release = pifsRelease) {
 
 export async function openAgentImage(projectRoot, imageId) {
   const resolved = resolveImageId(projectRoot, imageId);
-  const openImages = readOpenImages(projectRoot);
+  let openImages = readOpenImages(projectRoot);
+  let restarted = false;
   if (openImages[resolved]) {
-    return { alreadyOpen: true, ...openImages[resolved] };
+    if (openedImageIsAlive(openImages[resolved])) {
+      return { alreadyOpen: true, ...openImages[resolved] };
+    }
+    // The image this record names has exited. Forget it and open again,
+    // rather than hand back an endpoint nothing answers and say it is open.
+    const { [resolved]: exited, ...remaining } = openImages;
+    openImages = remaining;
+    writeOpenImages(projectRoot, openImages);
+    restarted = true;
   }
   fetchPifsRelease(pifsCloneDirectory(projectRoot));
   const launcher = new ScopedPharoLauncher({ projectRoot });
@@ -238,7 +249,15 @@ 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,
+    ...(restarted ? { restarted } : {}),
+    mountPath,
+    projectionPort,
+    ...(unappliedPin ? { warning: unappliedPin } : {}),
+  };
 }
 
 function unsupportedRunningImage(state, imageId) {

package/src/runtime.js

@@ -99,6 +99,32 @@ export function readOpenImage(projectRoot, imageId) {
   return open;
 }
 
+// A record in the project's runtime state says this project opened the image,
+// not that the image is still there. PLexus reclaims a dead image's port and
+// relaunches on the next open, so the only thing standing between a crashed
+// image and a working one is believing the record.
+export function imageProcessIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // The process is someone else's, which is still a process.
+    return error.code === "EPERM";
+  }
+}
+
+export function openedImageIsAlive(open) {
+  let state;
+  try {
+    state = readJson(open.statePath);
+  } catch {
+    return false;
+  }
+  const image = (state.images ?? []).find((candidate) => candidate.id === open.imageId);
+  return image?.status === "running" && imageProcessIsAlive(image.pid);
+}
+
 export function resolveMountPath(projectRoot, config, imageId) {
   const root = config.mountRoot ?? ".pharo-agent/mounts";
   return path.resolve(projectRoot, root, imageId);
@@ -131,6 +157,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("'", "''")}'`;
 }