@evref-bl/pharo-agent 0.3.10 → 0.5.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -1,68 +1,36 @@
 # pharo-agent
 
-`pharo-agent` is a terminal-first Pharo integration for Codex, Claude Code, and
-OpenCode. It has one small setup skill; a project receives the full Pharo
-guidance only after setup.
+`pharo-agent` gives a coding agent a live Pharo image: semantic tools over MCP,
+and the image's source projected as files it can read and edit. It works with
+Claude Code, Codex and OpenCode.
 
-Initialize the current directory for one selected agent host:
+## Setup
 
-```sh
-npx --yes @evref-bl/pharo-agent init --host codex
-```
-
-It writes a small conditional instruction block, `pharo.AGENTS.md`, and copies
-on-demand Pharo workflow skills and references from the pinned MCP template
-package. It does not install an agent-host MCP server.
-
-`init` acts on the current directory and never searches above it. If that
-directory has no `plexus.json`, it creates one that declares the
-project and no image; an existing one is left untouched. It refuses to run
-inside an enclosing PLexus project rather than initializing that project root.
-
-Register the image the project needs before the first `open`:
+In the project directory:
 
 ```sh
-pharo-agent image add dev --template 'Pharo 13.0 - 64bit (stable)'
+npx --yes @evref-bl/pharo-agent init --host <claude|codex|opencode>
 ```
 
-`image add` registers a template-created image with the pinned MCP load policy,
-and the first one registered becomes the default. `image list`,
-`image use <id>` (change the default) and `image remove <id>` cover the rest;
-an open image must be closed before its declaration is removed.
-
-`open` starts an image through PLexus, loads PIFS, and mounts its projection
-below `.pharo-agent/mounts`. `close` unmounts the projection and closes the
-PLexus image. `pharo` calls any exposed MCP tool through the same project
-route, while `mcp` exposes that tool surface as a command-scoped stdio MCP
-server.
-
-Several images can be open at once. `open`, `close`, `status`, `pharo` and
-`mcp` all accept `--image <id>`; without it the default image answers, so a
-project with one image never mentions an image at all. `open --image <id>`
-adds an image without closing the others, and `close` without `--image` closes
-every image this project opened. Over `mcp`, each Pharo tool takes the same
-optional `image` argument.
-
-Pass `--mount-root <path>` to `init` to use a different projection root.
+That is all of it. `init` writes the project's Pharo guidance and copies the
+workflow skills that guidance refers to. From there the agent registers the
+image the project needs, opens it and uses its tools by following what was
+written; ask it for Pharo work as you would for anything else.
 
 ## Requirements
 
-PIFS currently supports the macOS workflow and needs
-[fuse-t](https://www.fuse-t.org/). Its matching daemon is downloaded by PIFS;
-Go is not required at runtime.
+Node 22.12 or later.
 
-The CLI pins released MCP and PLexus dependencies. PLexus, in turn, pins the
-MCP release used to prepare the image; PIFS is loaded at its own exact release
-from the image.
+The source projection currently supports macOS and needs
+[fuse-t](https://www.fuse-t.org/). Its daemon is downloaded for you.
 
-## Host setup
+## What the agent gets
 
-Codex and Claude Code can install the repository as a plugin. Its only global
-skill initializes the current project; it does not add an MCP server or the
-Pharo workflow catalogue to every chat. OpenCode uses the same CLI command
-with `--host opencode`.
+Reference, for reading rather than typing: these are the commands the guidance
+hands to the agent.
 
-After initialization, the selected host guide says to read
-`pharo.AGENTS.md` only for Pharo work. That guide points to local workflow
-skills and references on demand. In the chat that runs setup, read that file
-before beginning Pharo work; later chats load the conditional guidance normally.
+- [Hosts](docs/hosts.md) — what `init` writes, and installing as a plugin.
+- [Images](docs/images.md) — templates and categories, several images at once,
+  Pharo versions outside the MCP range.
+- [Tools](docs/tools.md) — the advertised surface, finding the rest, and the
+  stdio bundle.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.3.10",
+  "version": "0.5.0",
   "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": "1.5.1",
-    "@evref-bl/plexus": "0.4.8",
-    "@evref-bl/plexus-gateway": "0.4.8",
+    "@evref-bl/pharo-mcp": "2.1.0",
+    "@evref-bl/plexus": "0.5.2",
+    "@evref-bl/plexus-gateway": "0.5.2",
     "@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.3.10",
+  "version": "0.5.0",
   "description": "Terminal-first Pharo image setup for coding agents.",
   "author": {
     "name": "Evref-BL",

package/skills/pharo-setup/SKILL.md

@@ -8,10 +8,11 @@ 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.3.10 init --host codex
+npx --yes @evref-bl/pharo-agent@0.5.0 init --host claude
 ```
 
-Use `--host claude` in Claude Code and `--host opencode` in OpenCode.
+Name the host this chat runs in: `--host claude` in Claude Code,
+`--host codex` in Codex, `--host opencode` in OpenCode.
 Do not configure an MCP server in the agent host. The command adds only a
 conditional instruction block, so Pharo guidance stays out of unrelated work.
 
@@ -19,9 +20,11 @@ Setup initializes the current directory, creating `plexus.json` with
 no image when it is absent. Register one before the first `pharo-agent open`:
 
 ```sh
-pharo-agent image list
+pharo-agent image templates
 pharo-agent image add dev --template '<launcher template name>'
 ```
 
+`image templates` names what the launcher offers, with the category of each.
+
 After setup, read `pharo.AGENTS.md` in this chat before doing Pharo work. A
 new chat picks up the conditional project guidance automatically.

package/src/cli.js

@@ -1,7 +1,13 @@
+import { hostChoices, hostList } from "./hosts.js";
 import { initialize } from "./init.js";
 import { addImage, listImages, removeImage, useImage } from "./images.js";
 import { callImageTool, listImageTools, serveImagesMcp } from "./gateway.js";
-import { agentImageStatus, closeAgentImage, openAgentImage } from "./live.js";
+import {
+  agentImageStatus,
+  closeAgentImage,
+  listImageTemplates,
+  openAgentImage,
+} from "./live.js";
 import { findProjectRoot } from "./project.js";
 import { readOpenImage } from "./runtime.js";
 
@@ -22,7 +28,7 @@ function parseInit(args) {
     }
     throw new Error(`Unknown init option: ${option}`);
   }
-  if (!host) throw new Error("init requires --host <codex|claude|opencode>");
+  if (!host) throw new Error(`init requires --host <${hostChoices()}>`);
   return { host, mountRoot };
 }
 
@@ -32,7 +38,11 @@ function parseImageAdd(args) {
     throw new Error("image add requires an image id");
   }
   const parsed = { id };
-  const options = { "--template": "template", "--profile": "profile" };
+  const options = {
+    "--template": "template",
+    "--category": "category",
+    "--profile": "profile",
+  };
   for (let index = 0; index < rest.length; index += 1) {
     const option = rest[index];
     const key = options[option];
@@ -65,9 +75,10 @@ function takeImageOption(args) {
 function usage() {
   return [
     "Usage:",
-    "  pharo-agent init --host <codex|claude|opencode> [--mount-root <path>]",
+    `  pharo-agent init --host <${hostChoices()}> [--mount-root <path>]`,
     "  pharo-agent image list",
-    "  pharo-agent image add <id> --template <name> [--profile <id>]",
+    "  pharo-agent image templates",
+    "  pharo-agent image add <id> --template <name> [--category <name>] [--profile <id>]",
     "  pharo-agent image use <id>",
     "  pharo-agent image remove <id>",
     "  pharo-agent open [--image <id>]",
@@ -106,7 +117,10 @@ export async function main(args) {
     console.log(JSON.stringify({ ok: true, ...result }, null, 2));
     return;
   }
-  if (!command || command === "--help" || command === "help") {
+  // A caller reaching for help is asking the same question wherever the word
+  // lands, and `image add --help` answering that it needs an image id is no
+  // answer at all.
+  if (!command || args.some((value) => value === "--help" || value === "help")) {
     console.log(usage());
     return;
   }
@@ -118,6 +132,15 @@ export async function main(args) {
       console.log(JSON.stringify({ ok: true, ...listImages(projectRoot) }, null, 2));
       return;
     }
+    if (subcommand === "templates") {
+      requireNoArguments("image templates", imageArgs);
+      console.log(JSON.stringify(
+        { ok: true, ...(await listImageTemplates(projectRoot)) },
+        null,
+        2,
+      ));
+      return;
+    }
     if (subcommand === "add") {
       console.log(JSON.stringify({ ok: true, ...addImage(projectRoot, parseImageAdd(imageArgs)) }, null, 2));
       return;
@@ -146,6 +169,9 @@ export async function main(args) {
   }
   if (command === "status") {
     requireNoArguments(command, commandArgs);
+    if (image) {
+      throw new Error("status reports every open image and does not accept --image");
+    }
     console.log(JSON.stringify({ ok: true, ...agentImageStatus(projectRoot) }, null, 2));
     return;
   }

package/src/gateway.js

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 import { PlexusGateway } from "@evref-bl/plexus-gateway";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -7,6 +8,10 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { readJson, readOpenImage, selectRunningImage } 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.
+export const { version } = createRequire(import.meta.url)("../package.json");
+
 export async function imageGateway(projectRoot, open) {
   const state = readJson(open.statePath);
   const { image, mcpServerId } = selectRunningImage(state, open.imageId);
@@ -75,17 +80,17 @@ export async function serveImagesMcp(projectRoot, defaultImage) {
   const defaultOpen = readOpenImage(projectRoot, defaultImage);
   const tools = (await listImageTools(projectRoot, defaultOpen))
     .map((tool) => withImageSelector(tool, defaultImage));
-  const toolNames = new Set(tools.map((tool) => tool.name));
 
   const server = new Server(
-    { name: "pharo-agent", version: "0.0.0" },
+    { name: "pharo-agent", version },
     { capabilities: { tools: {} } },
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    if (!toolNames.has(request.params.name)) {
-      throw new Error(`Unknown Pharo tool: ${request.params.name}`);
-    }
+    // Listed tools are the common ones, not the whole catalogue, and the image
+    // answers for any tool it holds. Refusing a name this list does not carry
+    // would hide tools that tool_search just found, and the image's own error
+    // is the better answer for a name nothing holds.
     const { image, ...argumentsValue } = request.params.arguments ?? {};
     const open = readOpenImage(projectRoot, image);
     return toolResult(

package/src/hosts.js

@@ -0,0 +1,29 @@
+// The agent hosts this CLI initializes, in the order they are offered. One
+// list, so the usage line, the error message and the documentation cannot
+// drift apart or disagree about which hosts exist.
+export const supportedHosts = [
+  { id: "claude", name: "Claude Code", guide: "CLAUDE.md", plugin: true },
+  { id: "codex", name: "Codex", guide: "AGENTS.md", plugin: true },
+  { id: "opencode", name: "OpenCode", guide: "AGENTS.md", plugin: false },
+];
+
+export const hostIds = supportedHosts.map((host) => host.id);
+
+export function hostNamed(id) {
+  return supportedHosts.find((host) => host.id === id);
+}
+
+export function guideForHost(id) {
+  return hostNamed(id)?.guide;
+}
+
+// "claude|codex|opencode", for the usage line.
+export function hostChoices() {
+  return hostIds.join("|");
+}
+
+// "claude, codex, or opencode", for a sentence.
+export function hostList() {
+  if (hostIds.length < 2) return hostIds.join("");
+  return `${hostIds.slice(0, -1).join(", ")}, or ${hostIds.at(-1)}`;
+}

package/src/images.js

@@ -37,7 +37,7 @@ export function listImages(projectRoot) {
   };
 }
 
-export function addImage(projectRoot, { id, template, profile }) {
+export function addImage(projectRoot, { id, template, category, profile }) {
   const config = readProjectConfig(projectRoot);
   const images = Array.isArray(config.images) ? config.images : [];
   if (images.some((image) => image.id === id)) {
@@ -57,6 +57,7 @@ export function addImage(projectRoot, { id, template, profile }) {
       kind: "template",
       ...(profile ? { profileId: profile } : {}),
       templateName: template,
+      ...(category ? { templateCategory: category } : {}),
       cleanupPolicy: "workspace_cleanup_only",
     },
   };
@@ -66,7 +67,13 @@ export function addImage(projectRoot, { id, template, profile }) {
   if (isDefault) {
     writeConfig(projectRoot, { ...pluginConfig, defaultImage: id });
   }
-  return { id, imageName, isDefault, templateName: template };
+  return {
+    id,
+    imageName,
+    isDefault,
+    templateName: template,
+    ...(category ? { templateCategory: category } : {}),
+  };
 }
 
 export function useImage(projectRoot, id) {

package/src/init.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { templateDirectory as mcpTemplateDirectory } from "@evref-bl/pharo-mcp";
+import { guideForHost, hostList } from "./hosts.js";
 import {
   createProjectConfig,
   enclosingProjectRoot,
@@ -9,14 +10,12 @@ import {
   projectConfigPath,
 } from "./project.js";
 
+// The host guide is the user's file, so our few lines are fenced off inside
+// it. `pharo.AGENTS.md` is ours whole, and needs no fence: one sentence says
+// where it came from, which a reader can act on and init can recognize.
 const managedStart = "<!-- pharo-agent:begin -->";
 const managedEnd = "<!-- pharo-agent:end -->";
-
-const hostGuide = {
-  claude: "CLAUDE.md",
-  codex: "AGENTS.md",
-  opencode: "AGENTS.md",
-};
+const generatedBy = "Generated by `pharo-agent init`";
 
 function copyDirectory(source, target) {
   for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
@@ -63,10 +62,7 @@ function writeIfMissing(filePath, content) {
 function assertGeneratedGuideCanBeUpdated(filePath) {
   if (!fs.existsSync(filePath)) return;
   const content = fs.readFileSync(filePath, "utf8");
-  if (
-    content.trimEnd() !== pharoGuide().trimEnd()
-    && (!content.includes(managedStart) || !content.includes(managedEnd))
-  ) {
+  if (!content.includes(generatedBy) && !content.includes(managedStart)) {
     throw new Error(`Refusing to replace user-owned ${filePath}`);
   }
 }
@@ -78,23 +74,40 @@ function guidance() {
 function pharoGuide() {
   return `# Pharo project guide
 
+${generatedBy}. Edits here are replaced the next time it runs.
+
 \`plexus.json\` declares this project's images. A freshly initialized
 project declares none; register one before the first \`pharo-agent open\`:
 
 \`\`\`sh
+pharo-agent image templates
 pharo-agent image list
 pharo-agent image add dev --template '<launcher template name>'
 \`\`\`
 
+\`image templates\` names the templates the launcher offers, with the category
+of each; a name two categories offer also needs \`--category <name>\`. Any
+version the launcher offers can be registered, and one outside the MCP range
+opens without MCP tools or a source projection, saying so.
+
 \`image add\` makes the first registered image the default. \`pharo-agent image
 use <id>\` changes the default, and \`pharo-agent image remove <id>\` drops a
 declaration. Close an image before removing its declaration.
 
 Use \`pharo-agent open\` before live-image work and edit projected source under
-\`.pharo-agent/mounts\`. Use \`pharo-agent pharo list\` to inspect the complete
-live MCP tool surface and \`pharo-agent pharo <tool> [arguments-json]\` to call
-a tool. \`pharo-agent mcp\` exposes the image as a command-scoped stdio MCP
-server.
+\`.pharo-agent/mounts\`. Call a tool with
+\`pharo-agent pharo <tool> [arguments-json]\`, and \`pharo-agent mcp\` exposes the
+image as a command-scoped stdio MCP server.
+
+\`pharo-agent pharo list\` names the tools the image advertises, which are the
+common ones rather than all of it. Find the rest through the catalogue rather
+than guessing at a name, then call one the same way as any other:
+
+\`\`\`sh
+pharo-agent pharo tool_search '{"query":"repository commit"}'
+pharo-agent pharo tool_get '{"name":"repository_commit"}'
+pharo-agent pharo repository_commit '{"name":"MCP","message":"..."}'
+\`\`\`
 
 Several images can be open at once. Every image-facing command takes
 \`--image <id>\`; without it the default image answers. \`pharo-agent open
@@ -151,9 +164,9 @@ function resolveInitProjectRoot(cwd) {
 }
 
 export function initialize({ host, mountRoot, cwd = process.cwd() }) {
-  const guideName = hostGuide[host];
+  const guideName = guideForHost(host);
   if (!guideName) {
-    throw new Error("--host must be codex, claude, or opencode");
+    throw new Error(`--host must be ${hostList()}`);
   }
 
   const { projectRoot, createdProjectConfig } = resolveInitProjectRoot(cwd);
@@ -173,7 +186,7 @@ export function initialize({ host, mountRoot, cwd = process.cwd() }) {
     );
   }
   writeIfMissing(path.join(directory, ".gitignore"), "mounts/\nruntime/\n");
-  updateManagedBlock(pharoGuidePath, pharoGuide());
+  fs.writeFileSync(pharoGuidePath, pharoGuide());
   const templates = mcpTemplateDirectory();
   copyDirectory(path.join(templates, "pharo-references"), path.join(directory, "references"));
   copyDirectory(path.join(templates, "pharo-skills"), path.join(directory, "skills"));

package/src/live.js

@@ -21,7 +21,13 @@ import {
   writeOpenImages,
 } from "./runtime.js";
 
-export const pifsRelease = "v0.4.1";
+export const pifsRelease = "v0.6.0";
+
+// The class-side PIFSServer messages this plugin sends into the image. The
+// release automation checks that a published PIFS still implements them: a pin
+// bump that leaves a removed selector in place passes every test here, because
+// the tests read generated source, and fails only in a live image.
+export const pifsSelectors = ["startMountedAt:named:", "stopOn:"];
 
 export function pifsStartCode(mountPath, imageName) {
   return `Metacello new
@@ -29,37 +35,66 @@ export function pifsStartCode(mountPath, imageName) {
 	repository: 'github://Evref-BL/pharo-image-fs:${pifsRelease}/src';
 	load: 'Core'.
 ((Smalltalk globals at: #PIFSServer)
-	startOn: 0
-	mountAt: ${smalltalkString(mountPath)} asFileReference
+	startMountedAt: ${smalltalkString(mountPath)} asFileReference
 	named: ${smalltalkString(imageName)}) port`;
 }
 
-export function resultPrintString(result) {
-  // MCP tool results carry the image's answer as JSON inside a text content part.
-  if (typeof result === "string") {
+export function pifsStopCode(projectionPort) {
+  return `(Smalltalk globals at: #PIFSServer) stopOn: ${projectionPort}`;
+}
+
+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.
+  if (typeof value === "string") {
     try {
-      return resultPrintString(JSON.parse(result));
+      return namedPrintString(JSON.parse(value));
     } catch {
       return undefined;
     }
   }
-  if (!result || typeof result !== "object") return undefined;
-  if (typeof result.resultPrintString === "string") return result.resultPrintString;
-  for (const value of Object.values(result)) {
-    const found = resultPrintString(value);
+  if (!value || typeof value !== "object") return undefined;
+  if (typeof value.resultPrintString === "string") return value.resultPrintString;
+  for (const each of Object.values(value)) {
+    const found = namedPrintString(each);
     if (found) return found;
   }
   return undefined;
 }
 
+function textPartText(result) {
+  if (!result || typeof result !== "object" || !Array.isArray(result.content)) {
+    return undefined;
+  }
+  const part = result.content.find(
+    (candidate) =>
+      candidate
+      && candidate.type === "text"
+      && typeof candidate.text === "string",
+  );
+  const text = part?.text.trim();
+  return text === "" ? undefined : text;
+}
+
+export function resultPrintString(result) {
+  // A server answering with structured content names the print string. In the
+  // content-only mode every MCP server defaults to, the text part is the print
+  // string, so a bare `60341` arrives as the whole answer.
+  return namedPrintString(result) ?? textPartText(result);
+}
 
-export function needsImageCreation(listed, imageId) {
+export function imageCreationPlan(listed, imageId) {
   const summary = listed.images.find((image) => image.imageId === imageId);
   if (!summary) {
     throw new Error(`PLexus does not know image ${imageId}.`);
   }
   // PLexus reports an image it has no runtime state for as declared.
-  return summary.status === "declared";
+  if (summary.status === "declared") return "create";
+  // A creation that failed leaves runtime state that blocks both a retry and a
+  // fresh declaration of the same id, so the id would be spent for good. Clear
+  // it and create again.
+  if (summary.status === "failed") return "reset";
+  return "none";
 }
 
 // The launcher resolves a template name against its default group only, so an
@@ -156,8 +191,10 @@ export async function openAgentImage(projectRoot, imageId) {
   }
   fetchPifsRelease(pifsCloneDirectory(projectRoot));
   const launcher = new ScopedPharoLauncher({ projectRoot });
-  const created = needsImageCreation(launcher.listImages(), resolved);
+  const plan = imageCreationPlan(launcher.listImages(), resolved);
+  const created = plan !== "none";
   if (created) {
+    if (plan === "reset") await launcher.resetImage(resolved);
     await resolveTemplateCategory(projectRoot, launcher, resolved);
     await launcher.createImage(resolved);
   }
@@ -170,9 +207,18 @@ export async function openAgentImage(projectRoot, imageId) {
   try {
     ({ image, mcpServerId } = selectRunningImage(opened.state, resolved));
   } catch (error) {
-    // The image is running but unusable to us, so do not leave it behind.
-    await closeProject({ projectRoot, imageIds: [resolved] }).catch(() => {});
-    throw error;
+    // An image whose Pharo version is outside the MCP contract still runs, and
+    // is still worth having: the caller asked for that version, and the tools
+    // it cannot offer are the only thing missing. Keep it, and say what is gone.
+    const withoutMcp = unsupportedRunningImage(opened.state, resolved);
+    if (!withoutMcp) {
+      // The image is running but unusable to us, so do not leave it behind.
+      await closeProject({ projectRoot, imageIds: [resolved] }).catch(() => {});
+      throw error;
+    }
+    const open = { statePath: opened.statePath, imageId: resolved, mcp: false };
+    writeOpenImages(projectRoot, { ...openImages, [resolved]: open });
+    return { ...open, created, warning: pharoMcpWarning(withoutMcp) };
   }
   const mountPath = resolveMountPath(projectRoot, readConfig(projectRoot), image.id);
   fs.mkdirSync(path.dirname(mountPath), { recursive: true });
@@ -182,8 +228,36 @@ export async function openAgentImage(projectRoot, imageId) {
     mcpServerId,
     mountPath,
   };
+  let projectionPort;
+  try {
+    projectionPort = await startProjection(projectRoot, open, image.imageName);
+  } catch (error) {
+    // The projection is half-started at best and nothing records it yet, so
+    // close the image rather than leave an image and a mount nothing owns.
+    await closeProject({ projectRoot, imageIds: [resolved] }).catch(() => {});
+    throw error;
+  }
+  writeOpenImages(projectRoot, { ...openImages, [resolved]: { ...open, projectionPort } });
+  return { imageId: image.id, created, mountPath, projectionPort };
+}
+
+function unsupportedRunningImage(state, imageId) {
+  const image = (state.images ?? []).find(
+    (candidate) => candidate.id === imageId && candidate.status === "running",
+  );
+  return image?.pharoMcpContract?.status === "unsupported" ? image : undefined;
+}
+
+export function pharoMcpWarning(image) {
+  const reason = image.pharoMcpContract?.reason
+    ?? "This image Pharo version is outside the supported Pharo MCP range.";
+  return `${reason} Image ${image.id} is open without MCP tools or a source projection;`
+    + " drive it with the Pharo command line instead.";
+}
+
+async function startProjection(projectRoot, open, imageName) {
   const result = await callImageTool(projectRoot, open, "image_evaluate", {
-    code: pifsStartCode(mountPath, image.imageName),
+    code: pifsStartCode(open.mountPath, imageName),
   });
   const projectionPort = Number(resultPrintString(result));
   if (!Number.isInteger(projectionPort) || projectionPort < 1) {
@@ -191,19 +265,22 @@ export async function openAgentImage(projectRoot, imageId) {
       `PIFS did not report a projection port: ${JSON.stringify(result).slice(0, 500)}`,
     );
   }
-  writeOpenImages(projectRoot, { ...openImages, [resolved]: { ...open, projectionPort } });
-  return { imageId: image.id, created, mountPath, projectionPort };
+  return projectionPort;
 }
 
 async function closeOneImage(projectRoot, openImages, imageId) {
   const open = openImages[imageId];
   let projectionError;
-  try {
-    await callImageTool(projectRoot, open, "image_evaluate", {
-      code: `(Smalltalk globals at: #PIFSServer) stopOn: ${open.projectionPort}`,
-    });
-  } catch (error) {
-    projectionError = error;
+  // An image opened without MCP has no projection to stop, and no route to
+  // ask over either.
+  if (open.projectionPort !== undefined) {
+    try {
+      await callImageTool(projectRoot, open, "image_evaluate", {
+        code: pifsStopCode(open.projectionPort),
+      });
+    } catch (error) {
+      projectionError = error;
+    }
   }
   const closed = await runLifecycle(
     () => closeProject({ projectRoot, imageIds: [imageId] }),
@@ -260,3 +337,21 @@ export function agentImageStatus(projectRoot) {
     })),
   };
 }
+
+export async function listImageTemplates(projectRoot) {
+  // `image add --template` takes a name the launcher must already know, and a
+  // name that lands in two categories needs the category as well, so answer
+  // both rather than leave the caller guessing a magic string.
+  const listed = await new ScopedPharoLauncher({ projectRoot }).listTemplates();
+  const counts = new Map();
+  for (const template of listed.templates) {
+    counts.set(template.name, (counts.get(template.name) ?? 0) + 1);
+  }
+  return {
+    templates: listed.templates.map((template) => ({
+      name: template.name,
+      category: template.templateCategory,
+      ...(counts.get(template.name) > 1 ? { categoryRequired: true } : {}),
+    })),
+  };
+}

package/src/runtime.js

@@ -90,6 +90,12 @@ export function readOpenImage(projectRoot, imageId) {
       `Image ${resolved} is not open. Run pharo-agent open${imageId ? ` --image ${resolved}` : ""} first.`,
     );
   }
+  if (open.mcp === false) {
+    throw new Error(
+      `Image ${resolved} is open without MCP, so it offers no Pharo tools. `
+        + "Register an image on a Pharo version the MCP contract supports to use them.",
+    );
+  }
   return open;
 }