@evref-bl/pharo-agent 0.12.2 → 0.13.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pharo-agent",
   "displayName": "Pharo Agent",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "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.12.2",
+  "version": "0.13.1",
   "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.12.2",
+  "version": "0.13.1",
   "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 or refresh Pharo tooling in this proj
 From the project root, run the released CLI that matches this plugin:
 
 ```sh
-npx --yes @evref-bl/pharo-agent@0.12.2 init --host claude
+npx --yes @evref-bl/pharo-agent@0.13.1 init --host claude
 ```
 
 Name the host this chat runs in: `--host claude` in Claude Code,

package/src/help.js

@@ -11,7 +11,8 @@ const commands = {
   "image list": {
     usage: "image list",
     description: "List the project's declared images and the default one, with the mount and\n"
-      + "projection port of each image this project has running.",
+      + "projection port of each image this project has running. An image this project\n"
+      + "started that has since exited is listed as exited.",
     example: "image list",
   },
   "image templates": {

package/src/images.js

@@ -1,6 +1,12 @@
 import { declareProjectImage, removeProjectImage } from "@evref-bl/plexus";
 import { configuredImages } from "./project.js";
-import { defaultImageId, readConfig, readRunningImages, writeConfig } from "./runtime.js";
+import {
+  defaultImageId,
+  readConfig,
+  readRunningImages,
+  recordedImageIsRunning,
+  writeConfig,
+} from "./runtime.js";
 
 export const defaultLoadScript = "pharo/load-mcp.st";
 
@@ -26,14 +32,20 @@ export function listImages(projectRoot) {
   return {
     ...(defaultImage ? { defaultImage } : {}),
     images: configured.map((image) => {
+      const record = running[image.id];
+      // A record says this project started the image, not that it is still
+      // there. One that crashed or was closed keeps its record until it is
+      // started or stopped again, and its route and mount lead nowhere.
+      const alive = record !== undefined && recordedImageIsRunning(record);
       // The record repeats the id it is keyed by; everything else in it is
       // runtime detail this list carries when the image is running.
-      const { imageId: _keyed, ...runtime } = running[image.id] ?? {};
+      const { imageId: _keyed, ...runtime } = alive ? record : {};
       return {
         id: image.id,
         imageName: image.imageName,
         isDefault: image.id === defaultImage,
-        running: Boolean(running[image.id]),
+        running: alive,
+        ...(record !== undefined && !alive ? { exited: true } : {}),
         ...runtime,
         templateName: image.create?.templateName,
         templateCategory: image.create?.templateCategory,

package/src/init.js

@@ -120,7 +120,9 @@ outside generated/copied files and outside the host guide's managed block.
 Refreshing project files does not install a newer package or upgrade image tools.
 
 \`plexus.json\` declares this project's images. A freshly initialized
-project declares none; register one before the first \`pharo-agent image start\`:
+project declares none; register one before the first image start. With the
+pharo-agent plugin enabled, that is \`image_templates\` and then \`image_add\`,
+with no shell. Otherwise:
 
 \`\`\`sh
 pharo-agent image templates
@@ -142,8 +144,9 @@ installed the image's source is also projected under \`.pharo-agent/mounts\`
 and can be edited as files; everywhere else the Pharo tools are the way in,
 and \`image start\` says so.
 
-With the pharo-agent plugin enabled for this project, the image's tools are MCP
-tools: start an image with \`image_start\` and call the rest by name. Without it,
+With the pharo-agent plugin enabled for this project, this is all MCP tools:
+declare an image with \`image_add\`, start it with \`image_start\`, and call the
+image's own tools by name. Without it,
 call a tool with \`pharo-agent pharo <tool> [arguments-json]\`, and
 \`pharo-agent mcp\` serves the same surface as a command-scoped stdio MCP
 server.

package/src/live.js

@@ -22,7 +22,7 @@ import {
   writeRunningImages,
 } from "./runtime.js";
 
-export const pifsRelease = "v0.9.2";
+export const pifsRelease = "v0.10.0";
 
 // fuse-t ships as a macOS installer package, so it lands in /usr/local
 // whatever Homebrew's prefix is. The unversioned symlink is what the daemon
@@ -86,6 +86,58 @@ export function pifsStopCode(projectionPort) {
   return `(Smalltalk globals at: #PIFSServer) stopOn: ${projectionPort}`;
 }
 
+// `mount` prints one "<source> on <path> (<options>)" line per mount, with the
+// path resolved, so a project under a symlink is looked for by its real path.
+export function isMountedAt(mountPath, mountTable) {
+  let realPath = mountPath;
+  try {
+    realPath = path.join(fs.realpathSync(path.dirname(mountPath)), path.basename(mountPath));
+  } catch {
+    // No parent directory, so nothing can be mounted there either.
+  }
+  return mountTable
+    .split("\n")
+    .some((line) => line.includes(` on ${mountPath} (`) || line.includes(` on ${realPath} (`));
+}
+
+function currentMountTable() {
+  return spawnSync("mount", [], { encoding: "utf8" }).stdout ?? "";
+}
+
+function unmount(mountPath) {
+  // What PIFSServer>>stopDaemon runs when it stops a projection itself.
+  if (spawnSync("umount", [mountPath], { stdio: "ignore" }).status !== 0) {
+    spawnSync("diskutil", ["unmount", mountPath], { stdio: "ignore" });
+  }
+}
+
+/**
+ * Unmount a projection whose image is gone.
+ *
+ * The mount is served by a PIFS daemon, a process of its own that reads the
+ * source over HTTP from the image. PIFS unmounts it from inside the image when
+ * it stops, which an image that crashed or was closed never does: the mount
+ * stays, every read in it fails with an I/O error, and it holds the path
+ * against the next projection. Unmounting is enough; the daemon exits with its
+ * mount.
+ *
+ * @param {string | undefined} mountPath
+ * @param {{ mountTable?: () => string, unmount?: (path: string) => void }} [host]
+ * @returns {boolean} whether something was unmounted
+ */
+export function releaseProjectionMount(mountPath, host = {}) {
+  const mountTable = host.mountTable ?? currentMountTable;
+  if (mountPath === undefined || !isMountedAt(mountPath, mountTable())) return false;
+  (host.unmount ?? unmount)(mountPath);
+  if (isMountedAt(mountPath, mountTable())) {
+    throw new Error(
+      `The source projection of an image that is gone is still mounted at ${mountPath},`
+        + ` and could not be unmounted. Run umount ${JSON.stringify(mountPath)}, then try again.`,
+    );
+  }
+  return true;
+}
+
 function namedPrintString(value) {
   // Structured results name the print string, somewhere under the envelope,
   // and reach us either as an object or as JSON inside a text part.
@@ -208,6 +260,11 @@ export async function startAgentImage(projectRoot, imageId) {
     restarted = true;
   }
   if (projectionAvailability().available) {
+    // This project has no live image at this mount path now: none was
+    // recorded, or the one recorded has exited. Whatever is still mounted
+    // there was left by an image that is gone, and would hold the path
+    // against the projection about to be mounted.
+    releaseProjectionMount(resolveMountPath(projectRoot, readConfig(projectRoot), resolved));
     fetchPifsRelease(pifsCloneDirectory(projectRoot));
   }
   const launcher = new ScopedPharoLauncher({ projectRoot });
@@ -319,9 +376,14 @@ async function stopOneImage(projectRoot, runningImages, imageId) {
   // ask over either.
   if (record.projectionPort !== undefined) {
     try {
-      await callImageTool(projectRoot, record, "image_evaluate", {
-        code: pifsStopCode(record.projectionPort),
-      });
+      if (recordedImageIsRunning(record)) {
+        await callImageTool(projectRoot, record, "image_evaluate", {
+          code: pifsStopCode(record.projectionPort),
+        });
+      } else {
+        // PIFS stops a projection from inside its image, and this one is gone.
+        releaseProjectionMount(record.mountPath);
+      }
     } catch (error) {
       projectionError = error;
     }

package/src/mcpServer.js

@@ -11,8 +11,8 @@ import {
   version,
   withImageSelector,
 } from "./gateway.js";
-import { listImages } from "./images.js";
-import { startAgentImage, stopAgentImage } from "./live.js";
+import { addImage, listImages } from "./images.js";
+import { listImageTemplates, startAgentImage, stopAgentImage } from "./live.js";
 import { readRunningImage } from "./runtime.js";
 
 // The host loads only tool names and these instructions at session start and
@@ -26,15 +26,57 @@ and projecting image source as files on disk.
 Search these tools whenever the task involves Pharo, Smalltalk, a Tonel
 package, or a .st file. Start an image with image_start before calling the
 image's own tools, which are listed once an image answers; image_list says
-what is already running.
+what is already running. A project that declares no image yet needs
+image_templates and image_add first.
 
 The image advertises the common tools rather than all of it. Use tool_search
 and tool_get to find the rest, then call one by name like any other.`;
 
-// Listed whether or not an image is running, so the list is never empty. A
-// host that caches tools and ignores tools/list_changed would otherwise hold
-// an empty list for the whole session and never learn that one had started.
-const lifecycleTools = [
+// This server's own tools, in the order a project meets them: declare an
+// image, start it, and the image's tools join the list. Listed whether or not
+// an image is running, so the list is never empty — a host that caches tools
+// and ignores tools/list_changed would otherwise hold an empty list for the
+// whole session and never learn that one had started.
+const projectTools = [
+  {
+    name: "image_templates",
+    description:
+      "List the images Pharo Launcher can create, with the category of each. "
+      + "A template name that two categories offer is flagged, and needs its "
+      + "category when it is declared.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "image_add",
+    description:
+      "Declare an image in this project, from a template image_templates "
+      + "names. Declaring does not create the image: the first image_start "
+      + "does, from this template. The first image declared becomes the "
+      + "project's default.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "Short id this project calls the image by, such as dev.",
+        },
+        template: {
+          type: "string",
+          description: "Template name, exactly as image_templates gives it.",
+        },
+        category: {
+          type: "string",
+          description:
+            "Template category. Needed only for a name two categories offer.",
+        },
+        profile: {
+          type: "string",
+          description: "Pharo Launcher profile to create the image under.",
+        },
+      },
+      required: ["id", "template"],
+    },
+  },
   {
     name: "image_start",
     description:
@@ -56,7 +98,8 @@ const lifecycleTools = [
     name: "image_list",
     description:
       "List this project's declared images, which are running, and the route "
-      + "and mount of each running one.",
+      + "and mount of each running one. An image that was started and has "
+      + "exited since is listed as exited; image_start starts it again.",
     inputSchema: { type: "object", properties: {} },
   },
   {
@@ -91,8 +134,31 @@ async function runningImageTools(projectRoot, defaultImage) {
     // contributes no tools yet and the lifecycle tools say how to change that.
     return [];
   }
-  return (await listImageTools(projectRoot, running))
-    .map((tool) => withImageSelector(tool, running.imageId));
+  try {
+    return (await listImageTools(projectRoot, running))
+      .map((tool) => withImageSelector(tool, running.imageId));
+  } catch (error) {
+    // A record says this project started the image, not that it still
+    // answers: it may have exited, or hung. Failing the whole list would take
+    // image_start with it, and with it the one way back. image_list says
+    // which image is gone; stderr reaches the host's log.
+    console.error(`pharo-agent: image ${running.imageId} listed no tools: ${error.message}`);
+    return [];
+  }
+}
+
+// A schema is a description, not a guard: nothing between the model and here
+// enforces it, and a declaration missing its template would otherwise fail
+// somewhere further in, naming a field the caller never saw.
+function declarationFrom(argumentsValue) {
+  const { id, template, category, profile } = argumentsValue;
+  if (typeof id !== "string" || id === "") {
+    throw new Error("image_add needs the id this project will call the image by.");
+  }
+  if (typeof template !== "string" || template === "") {
+    throw new Error("image_add needs a template name, as image_templates gives it.");
+  }
+  return { id, template, category, profile };
 }
 
 export async function serveImagesMcp(resolveProjectRoot, defaultImage) {
@@ -108,10 +174,10 @@ export async function serveImagesMcp(resolveProjectRoot, defaultImage) {
     } catch {
       // No project here. The lifecycle tools are still listed rather than
       // nothing, so the host has a server that works and a call can say why.
-      return { tools: lifecycleTools };
+      return { tools: projectTools };
     }
     return {
-      tools: [...lifecycleTools, ...(await runningImageTools(projectRoot, defaultImage))],
+      tools: [...projectTools, ...(await runningImageTools(projectRoot, defaultImage))],
     };
   });
 
@@ -121,9 +187,15 @@ export async function serveImagesMcp(resolveProjectRoot, defaultImage) {
     // Throws when there is no project, which is the answer the caller needs.
     const projectRoot = resolveProjectRoot();
 
-    // Matched before the image's catalogue: these three names belong to this
+    // Matched before the image's catalogue: these names belong to this
     // server, and an image that happened to hold one must not decide what
     // starting an image means.
+    if (request.params.name === "image_templates") {
+      return toolResult({ ok: true, ...(await listImageTemplates(projectRoot)) });
+    }
+    if (request.params.name === "image_add") {
+      return toolResult({ ok: true, ...addImage(projectRoot, declarationFrom(argumentsValue)) });
+    }
     if (request.params.name === "image_start") {
       const started = await startAgentImage(projectRoot, selected);
       await server.sendToolListChanged();

package/src/runtime.js

@@ -23,11 +23,18 @@ export function configPath(projectRoot) {
   return path.join(pluginDirectory(projectRoot), "config.json");
 }
 
+// A project can hold a plexus.json this plugin never initialized, and now that
+// an image can be declared from a chat it is reached before `.pharo-agent`
+// exists. An absent settings file is a project with no settings, not an error
+// about a path the caller never named.
 export function readConfig(projectRoot) {
-  return readJson(configPath(projectRoot));
+  const filePath = configPath(projectRoot);
+  if (!fs.existsSync(filePath)) return {};
+  return readJson(filePath);
 }
 
 export function writeConfig(projectRoot, config) {
+  fs.mkdirSync(pluginDirectory(projectRoot), { recursive: true });
   fs.writeFileSync(configPath(projectRoot), `${JSON.stringify(config, null, 2)}\n`);
 }