@evref-bl/pharo-agent 0.10.1 → 0.11.0

package/.claude-plugin/plugin.json

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

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "image": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/pharo-agent.js", "mcp"]
+    }
+  }
+}

package/README.md

@@ -14,7 +14,7 @@ npx --yes @evref-bl/pharo-agent init --host <claude|codex|opencode>
 
 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
+image the project needs, starts it and uses its tools by following what was
 written; ask it for Pharo work as you would for anything else.
 
 ## Refreshing an existing project

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "private": false,
   "description": "Terminal-first Pharo integration for coding agents.",
   "license": "Apache-2.0",
@@ -16,6 +16,7 @@
     "bin",
     "src",
     "skills",
+    ".mcp.json",
     "plugin.json",
     ".agents",
     ".claude-plugin",
@@ -32,7 +33,7 @@
   },
   "dependencies": {
     "@evref-bl/pharo-mcp": "3.3.1",
-    "@evref-bl/plexus": "0.10.1",
+    "@evref-bl/plexus": "0.11.0",
     "@modelcontextprotocol/sdk": "1.32.1"
   },
   "devDependencies": {

package/plugin.json

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

package/skills/pharo-setup/SKILL.md

@@ -8,13 +8,35 @@ 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.10.1 init --host claude
+npx --yes @evref-bl/pharo-agent@0.11.0 init --host claude
 ```
 
 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.
+The command writes no host configuration. It adds a conditional instruction
+block and this project's own files, so Pharo guidance stays out of unrelated
+work.
+
+To get the image's tools as MCP tools in Claude Code, enable this plugin for
+this project rather than configuring a server by hand. Commit
+`.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "evref-bl": {
+      "source": {
+        "source": "git",
+        "url": "https://github.com/Evref-BL/pharo-agent-plugin.git"
+      }
+    }
+  },
+  "enabledPlugins": { "pharo-agent@evref-bl": true }
+}
+```
+
+A host reads that file when a session starts, so the tools appear in the next
+one. Enabling it per project keeps every other project untouched.
 
 After upgrading the plugin/CLI, re-run the setup command from the project root
 with the same host to refresh the generated guide and copied skills/references.
@@ -24,7 +46,8 @@ existing settings. Image declarations, runtime state, and live image code are
 preserved. This refresh does not install a newer package or upgrade image tools.
 
 Setup initializes the current directory, creating `plexus.json` with
-no image when it is absent. Register one before the first `pharo-agent open`:
+no image when it is absent. Register one before the first
+`pharo-agent image start`:
 
 ```sh
 pharo-agent image templates

package/src/cli.js

@@ -2,15 +2,11 @@ import { hostChoices, hostList } from "./hosts.js";
 import { usage } from "./help.js";
 import { initialize } from "./init.js";
 import { addImage, listImages, removeImage, useImage } from "./images.js";
-import { callImageTool, listImageTools, serveImagesMcp } from "./gateway.js";
-import {
-  agentImageStatus,
-  closeAgentImage,
-  listImageTemplates,
-  openAgentImage,
-} from "./live.js";
+import { callImageTool, listImageTools } from "./gateway.js";
+import { serveImagesMcp } from "./mcpServer.js";
+import { listImageTemplates, startAgentImage, stopAgentImage } from "./live.js";
 import { findProjectRoot } from "./project.js";
-import { readOpenImage } from "./runtime.js";
+import { readRunningImage } from "./runtime.js";
 
 function parseInit(args) {
   let host;
@@ -63,6 +59,21 @@ function parseImageAdd(args) {
   return parsed;
 }
 
+// `image start` and `image stop` name their subject, like `image use` and
+// `image remove`; `--image` stays on the commands that scope a call.
+function parseImageTarget(subcommand, args) {
+  const all = args.includes("--all");
+  const rest = args.filter((value) => value !== "--all");
+  const [id, ...extra] = rest;
+  if (extra.length > 0 || (id && id.startsWith("--"))) {
+    throw new Error(`image ${subcommand} takes one image id`);
+  }
+  if (all && subcommand !== "stop") {
+    throw new Error(`image ${subcommand} does not accept --all`);
+  }
+  return { id, all };
+}
+
 function takeImageOption(args) {
   const index = args.indexOf("--image");
   if (index === -1) return { image: undefined, rest: args };
@@ -115,6 +126,16 @@ export async function main(args) {
     console.log(JSON.stringify({ ok: true, ...result }, null, 2));
     return;
   }
+  // Above the project lookup on purpose: a host starts this in whatever
+  // directory it likes, which may hold no project at all, and a server that
+  // exits is a broken server in the host's list. It resolves a project per
+  // request instead, so the reason reaches whoever calls a tool.
+  if (command === "mcp") {
+    const { image: mcpImage, rest: mcpArgs } = takeImageOption(rest);
+    requireNoArguments(command, mcpArgs);
+    await serveImagesMcp(findProjectRoot, mcpImage);
+    return;
+  }
   const projectRoot = findProjectRoot();
   if (command === "image") {
     const [subcommand, ...imageArgs] = rest;
@@ -136,6 +157,24 @@ export async function main(args) {
       console.log(JSON.stringify({ ok: true, ...addImage(projectRoot, parseImageAdd(imageArgs)) }, null, 2));
       return;
     }
+    if (subcommand === "start") {
+      const { id } = parseImageTarget(subcommand, imageArgs);
+      console.log(JSON.stringify(
+        { ok: true, ...(await startAgentImage(projectRoot, id)) },
+        null,
+        2,
+      ));
+      return;
+    }
+    if (subcommand === "stop") {
+      const { id, all } = parseImageTarget(subcommand, imageArgs);
+      console.log(JSON.stringify(
+        { ok: true, ...(await stopAgentImage(projectRoot, id, { all })) },
+        null,
+        2,
+      ));
+      return;
+    }
     if (subcommand === "use" || subcommand === "remove") {
       const [id, ...extra] = imageArgs;
       if (!id || extra.length > 0) {
@@ -148,35 +187,12 @@ export async function main(args) {
     throw new Error(`Unsupported image command: ${subcommand ?? ""}\n${usage()}`);
   }
   const { image, rest: commandArgs } = takeImageOption(rest);
-  if (command === "open") {
-    requireNoArguments(command, commandArgs);
-    console.log(JSON.stringify({ ok: true, ...(await openAgentImage(projectRoot, image)) }, null, 2));
-    return;
-  }
-  if (command === "close") {
-    requireNoArguments(command, commandArgs);
-    console.log(JSON.stringify({ ok: true, ...(await closeAgentImage(projectRoot, image)) }, null, 2));
-    return;
-  }
-  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;
-  }
-  if (command === "mcp") {
-    requireNoArguments(command, commandArgs);
-    await serveImagesMcp(projectRoot, image);
-    return;
-  }
   if (command === "pharo") {
     const [toolName, argumentsJson, ...extra] = commandArgs;
     if (toolName === "list") {
       if (argumentsJson || extra.length > 0) throw new Error("pharo list does not accept arguments");
       console.log(JSON.stringify(
-        await listImageTools(projectRoot, readOpenImage(projectRoot, image)),
+        await listImageTools(projectRoot, readRunningImage(projectRoot, image)),
         null,
         2,
       ));
@@ -187,7 +203,7 @@ export async function main(args) {
     }
     const result = await callImageTool(
       projectRoot,
-      readOpenImage(projectRoot, image),
+      readRunningImage(projectRoot, image),
       toolName,
       parseToolArguments(argumentsJson),
     );

package/src/gateway.js

@@ -1,14 +1,7 @@
 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";
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
 import {
   readJson,
-  readOpenImage,
   selectRunningImage,
   unappliedPharoMcpPin,
 } from "./runtime.js";
@@ -20,15 +13,15 @@ export const { version } = createRequire(import.meta.url)("../package.json");
 // A route source is the directory, not the route. PLexus re-reads the state
 // file and the image's endpoint handoff every time it resolves one, so there
 // is nothing to register here and nothing that can go stale between the call
-// that opened the image and this one.
-export function imageGateway(projectRoot, open) {
-  const state = readJson(open.statePath);
-  const { image, mcpServerId } = selectRunningImage(state, open.imageId);
-  if (image.id !== open.imageId || mcpServerId !== open.mcpServerId) {
-    throw new Error(`The PLexus image ${open.imageId} changed; run pharo-agent open again.`);
+// that started the image and this one.
+export function imageGateway(projectRoot, running) {
+  const state = readJson(running.statePath);
+  const { image, mcpServerId } = selectRunningImage(state, running.imageId);
+  if (image.id !== running.imageId || mcpServerId !== running.mcpServerId) {
+    throw new Error(`The PLexus image ${running.imageId} changed; run pharo-agent image start again.`);
   }
   const gateway = new PlexusGateway({
-    routeSources: [{ projectRoot, statePath: open.statePath }],
+    routeSources: [{ projectRoot, statePath: running.statePath }],
     pharoScope: {
       projectId: state.projectId,
       workspaceId: state.workspaceId,
@@ -49,8 +42,8 @@ export function toolFailureMessage(error, image) {
   return unappliedPin ? `${error}\n${unappliedPin}` : error;
 }
 
-export async function callImageTool(projectRoot, open, toolName, argumentsValue) {
-  const { gateway, mcpServerId, image } = imageGateway(projectRoot, open);
+export async function callImageTool(projectRoot, running, toolName, argumentsValue) {
+  const { gateway, mcpServerId, image } = imageGateway(projectRoot, running);
   const result = await gateway.routeToImage({
     mcpServerId,
     toolName,
@@ -64,8 +57,8 @@ export async function callImageTool(projectRoot, open, toolName, argumentsValue)
   );
 }
 
-export async function listImageTools(projectRoot, open) {
-  const { gateway } = imageGateway(projectRoot, open);
+export async function listImageTools(projectRoot, running) {
+  const { gateway } = imageGateway(projectRoot, running);
   return gateway.refreshPharoTools();
 }
 
@@ -89,28 +82,3 @@ export function toolResult(data) {
   }
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
-
-export async function serveImagesMcp(projectRoot, defaultImage) {
-  const defaultOpen = readOpenImage(projectRoot, defaultImage);
-  const tools = (await listImageTools(projectRoot, defaultOpen))
-    .map((tool) => withImageSelector(tool, defaultImage));
-
-  const server = new Server(
-    { name: "pharo-agent", version },
-    { capabilities: { tools: {} } },
-  );
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    // 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(
-      await callImageTool(projectRoot, open, request.params.name, argumentsValue),
-    );
-  });
-
-  await server.connect(new StdioServerTransport());
-}

package/src/help.js

@@ -10,7 +10,8 @@ const commands = {
   },
   "image list": {
     usage: "image list",
-    description: "List the project's declared images, default image, and recorded open state.",
+    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.",
     example: "image list",
   },
   "image templates": {
@@ -21,55 +22,52 @@ const commands = {
   },
   "image add": {
     usage: "image add <id> --template <name> [--category <name>] [--profile <id>]",
-    description: "Declare an image with a required id and template name; open creates it later.\n"
+    description: "Declare an image with a required id and template name; image start creates it later.\n"
       + "Use --category for an ambiguous template name and --profile to choose a launcher profile.\n"
       + "The first declared image becomes the default.",
     example: "image add dev --template '<template name>'",
   },
   "image use": {
     usage: "image use <id>",
-    description: "Make the required declared image the project's default. It may already be open.",
+    description: "Make the required declared image the project's default. It may already be running.",
     example: "image use dev",
   },
   "image remove": {
     usage: "image remove <id>",
-    description: "Remove the required image declaration. Close the image first. Its image files are kept.\n"
+    description: "Remove the required image declaration. Stop the image first. Its image files are kept.\n"
       + "Removing the default image clears the default selection.",
     example: "image remove dev",
   },
-  open: {
-    usage: "open [--image <id>]",
-    description: "Create if needed and open an image with its tools and source projection. Omit --image\n"
-      + "to use the project's default image. Other open images stay open. Pharo versions outside\n"
-      + "the MCP support range open without tools or a source projection.",
-    example: "open --image dev",
+  "image start": {
+    usage: "image start [<id>]",
+    description: "Create if needed and start an image with its tools and source projection. Omit the id\n"
+      + "to use the project's default image. Images already running stay running. Pharo versions\n"
+      + "outside the MCP support range start without tools or a source projection.",
+    example: "image start dev",
   },
-  status: {
-    usage: "status",
-    description: "Report all images this project has open. This command does not accept --image.",
-    example: "status",
-  },
-  close: {
-    usage: "close [--image <id>]",
-    description: "Close the selected image and its source projection. Omitting --image closes all images\n"
-      + "this project opened, rather than only the default image.",
-    example: "close --image dev",
+  "image stop": {
+    usage: "image stop [<id>] [--all]",
+    description: "Stop the named image and its source projection, or the project's default image when\n"
+      + "no id is given. Use --all to stop every image this project started.",
+    example: "image stop dev",
   },
   mcp: {
     usage: "mcp [--image <id>]",
-    description: "Expose an open image's tools as a command-scoped stdio MCP server. Omit --image\n"
-      + "to use the project's default image. The server exits with this command.",
+    description: "Serve this project's images as a command-scoped stdio MCP server. Omit\n"
+      + "--image to use the project's default image. It starts whether or not an image\n"
+      + "is running: image_start starts one and the image's own tools join the list. The\n"
+      + "server exits with this command, and the plugin's .mcp.json starts it for a host.",
     example: "mcp --image dev",
   },
   "pharo list": {
     usage: "pharo list [--image <id>]",
-    description: "List an open image's advertised tools. Omit --image to use the project's default image.\n"
+    description: "List a running image's advertised tools. Omit --image to use the project's default image.\n"
       + "Use tool_search and tool_get to discover and inspect the rest of its catalogue.",
     example: "pharo list",
   },
   pharo: {
     usage: "pharo <tool> [arguments-json] [--image <id>]",
-    description: "Call a tool in an open image. Arguments must be a JSON object and default to {}.\n"
+    description: "Call a tool in a running image. Arguments must be a JSON object and default to {}.\n"
       + "Omit --image to use the project's default image. Inspect the tool's schema with tool_get\n"
       + "before calling it; a failed tool result makes the command exit unsuccessfully.",
     example: 'pharo tool_get \'{"name":"class_search"}\'',

package/src/images.js

@@ -4,13 +4,15 @@ import {
   readProjectConfig,
   writeProjectConfig,
 } from "./project.js";
-import { readConfig, readOpenImages, writeConfig } from "./runtime.js";
+import { defaultImageId, readConfig, readRunningImages, writeConfig } from "./runtime.js";
 
 export const defaultLoadScript = "pharo/load-mcp.st";
 
-function assertNoOpenImage(projectRoot, imageId, action) {
-  if (readOpenImages(projectRoot)[imageId]) {
-    throw new Error(`Image ${imageId} is open. Run pharo-agent close before ${action}.`);
+function assertNotRunning(projectRoot, imageId, action) {
+  if (readRunningImages(projectRoot)[imageId]) {
+    throw new Error(
+      `Image ${imageId} is running. Run pharo-agent image stop ${imageId} before ${action}.`,
+    );
   }
 }
 
@@ -21,19 +23,31 @@ function derivedImageName(projectRoot, imageId) {
 
 export function listImages(projectRoot) {
   const configured = configuredImages(projectRoot);
-  const open = readOpenImages(projectRoot);
-  const defaultImage = readConfig(projectRoot).defaultImage
-    ?? (configured.length === 1 ? configured[0].id : undefined);
+  const running = readRunningImages(projectRoot);
+  let defaultImage;
+  try {
+    defaultImage = defaultImageId(projectRoot);
+  } catch {
+    // Several declared and none chosen. The list is how a caller finds that
+    // out, so it answers rather than raising the question back at them.
+    defaultImage = undefined;
+  }
   return {
     ...(defaultImage ? { defaultImage } : {}),
-    images: configured.map((image) => ({
-      id: image.id,
-      imageName: image.imageName,
-      isDefault: image.id === defaultImage,
-      open: Boolean(open[image.id]),
-      templateName: image.create?.templateName,
-      templateCategory: image.create?.templateCategory,
-    })),
+    images: configured.map((image) => {
+      // 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] ?? {};
+      return {
+        id: image.id,
+        imageName: image.imageName,
+        isDefault: image.id === defaultImage,
+        running: Boolean(running[image.id]),
+        ...runtime,
+        templateName: image.create?.templateName,
+        templateCategory: image.create?.templateCategory,
+      };
+    }),
   };
 }
 
@@ -53,7 +67,6 @@ export function addImage(projectRoot, request) {
   const image = {
     id,
     imageName,
-    active: true,
     mcp: { loadScript: defaultLoadScript, loadPolicy: "ifMissing" },
     create: {
       kind: "template",
@@ -92,7 +105,7 @@ export function removeImage(projectRoot, id) {
   if (!images.some((image) => image.id === id)) {
     throw new Error(`Image ${id} is not configured.`);
   }
-  assertNoOpenImage(projectRoot, id, "removing it");
+  assertNotRunning(projectRoot, id, "removing it");
   writeProjectConfig(projectRoot, {
     ...config,
     images: images.filter((image) => image.id !== id),

package/src/init.js

@@ -120,7 +120,7 @@ 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 open\`:
+project declares none; register one before the first \`pharo-agent image start\`:
 
 \`\`\`sh
 pharo-agent image templates
@@ -131,16 +131,20 @@ 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.
+starts 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.
+declaration. Stop an image before removing its declaration.
 
-Use \`pharo-agent open\` before live-image work and edit projected source under
-\`.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.
+Use \`pharo-agent image start\` before live-image work and edit projected source
+under \`.pharo-agent/mounts\`.
+
+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,
+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.
 
 \`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
@@ -152,11 +156,11 @@ 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
---image <id>\` opens another image without closing the first,
-\`pharo-agent status\` lists what is open, and \`pharo-agent close\` closes
-everything this project opened.
+Several images can run at once. \`pharo-agent image start <id>\` and
+\`pharo-agent image stop <id>\` name their image, \`pharo\` and \`mcp\` take
+\`--image <id>\`, and without either the default image answers.
+\`pharo-agent image list\` says which are running, and
+\`pharo-agent image stop --all\` stops every one this project started.
 
 Image, Tonel, Iceberg, disk Git, and host processes are separate states.
 

package/src/live.js

@@ -11,19 +11,18 @@ import {
 import { callImageTool } from "./gateway.js";
 import { readProjectConfig, writeProjectConfig } from "./project.js";
 import {
-  defaultImageId,
-  openedImageIsAlive,
   readConfig,
-  readOpenImages,
+  readRunningImages,
+  recordedImageIsRunning,
   resolveImageId,
   resolveMountPath,
   selectRunningImage,
   smalltalkString,
   unappliedPharoMcpPin,
-  writeOpenImages,
+  writeRunningImages,
 } from "./runtime.js";
 
-export const pifsRelease = "v0.9.1";
+export const pifsRelease = "v0.9.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
@@ -85,17 +84,25 @@ export function resultPrintString(result) {
   return namedPrintString(result) ?? textPartText(result);
 }
 
+/**
+ * The status is spelled out rather than taken as a string: this read branched
+ * for a long time on "declared" and "failed", which PLexus does not report,
+ * so a declared image was never created and the launch that followed failed
+ * on an image that was not there. Naming the four it does report makes the
+ * typecheck reject a fifth.
+ *
+ * @param {{ images: { imageId: string,
+ *   status: "absent" | "stopped" | "starting" | "running" }[] }} listed
+ * @param {string} 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.
-  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";
+  // "absent" is PLexus's word for no image file on disk, which is what a
+  // declared image looks like until something creates it.
+  if (summary.status === "absent") return "create";
   return "none";
 }
 
@@ -185,70 +192,69 @@ export function fetchPifsRelease(cloneDirectory, release = pifsRelease) {
   return git("fetch", "--tags", "--quiet", "origin");
 }
 
-export async function openAgentImage(projectRoot, imageId) {
+export async function startAgentImage(projectRoot, imageId) {
   const resolved = resolveImageId(projectRoot, imageId);
-  let openImages = readOpenImages(projectRoot);
+  let runningImages = readRunningImages(projectRoot);
   let restarted = false;
-  if (openImages[resolved]) {
-    if (openedImageIsAlive(openImages[resolved])) {
-      return { alreadyOpen: true, ...openImages[resolved] };
+  if (runningImages[resolved]) {
+    if (recordedImageIsRunning(runningImages[resolved])) {
+      return { alreadyRunning: true, ...runningImages[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);
+    // The image this record names has exited. Forget it and start again,
+    // rather than hand back an endpoint nothing answers and call it running.
+    const { [resolved]: exited, ...remaining } = runningImages;
+    runningImages = remaining;
+    writeRunningImages(projectRoot, runningImages);
     restarted = true;
   }
   fetchPifsRelease(pifsCloneDirectory(projectRoot));
   const launcher = new ScopedPharoLauncher({ projectRoot });
-  const plan = imageCreationPlan(launcher.listImages(), resolved);
+  const plan = imageCreationPlan(await 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);
   }
-  const opened = await runLifecycle(
+  const started = await runLifecycle(
     () => startProjectImage({ projectRoot, imageId: resolved }),
-    `PLexus could not open image ${resolved}.`,
+    `PLexus could not start image ${resolved}.`,
   );
   let image;
   let mcpServerId;
   try {
-    ({ image, mcpServerId } = selectRunningImage(opened.state, resolved));
+    ({ image, mcpServerId } = selectRunningImage(started.state, resolved));
   } catch (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);
+    const withoutMcp = unsupportedRunningImage(started.state, resolved);
     if (!withoutMcp) {
       // The image is running but unusable to us, so do not leave it behind.
       await stopProjectImage({ projectRoot, imageId: 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 record = { statePath: started.statePath, imageId: resolved, mcp: false };
+    writeRunningImages(projectRoot, { ...runningImages, [resolved]: record });
+    return { ...record, created, warning: pharoMcpWarning(withoutMcp) };
   }
   const mountPath = resolveMountPath(projectRoot, readConfig(projectRoot), image.id);
   fs.mkdirSync(path.dirname(mountPath), { recursive: true });
-  const open = {
-    statePath: opened.statePath,
+  const record = {
+    statePath: started.statePath,
     imageId: image.id,
     mcpServerId,
     mountPath,
   };
   let projectionPort;
   try {
-    projectionPort = await startProjection(projectRoot, open, image.imageName);
+    projectionPort = await startProjection(projectRoot, record, 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.
+    // stop the image rather than leave an image and a mount nothing owns.
     await stopProjectImage({ projectRoot, imageId: resolved }).catch(() => {});
     throw error;
   }
-  writeOpenImages(projectRoot, { ...openImages, [resolved]: { ...open, projectionPort } });
+  writeRunningImages(projectRoot, { ...runningImages, [resolved]: { ...record, projectionPort } });
   const unappliedPin = unappliedPharoMcpPin(image);
   return {
     imageId: image.id,
@@ -270,13 +276,13 @@ function unsupportedRunningImage(state, imageId) {
 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;`
+  return `${reason} Image ${image.id} is running 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(open.mountPath, imageName),
+async function startProjection(projectRoot, record, imageName) {
+  const result = await callImageTool(projectRoot, record, "image_evaluate", {
+    code: pifsStartCode(record.mountPath, imageName),
   });
   const projectionPort = Number(resultPrintString(result));
   if (!Number.isInteger(projectionPort) || projectionPort < 1) {
@@ -287,76 +293,73 @@ async function startProjection(projectRoot, open, imageName) {
   return projectionPort;
 }
 
-async function closeOneImage(projectRoot, openImages, imageId) {
-  const open = openImages[imageId];
+async function stopOneImage(projectRoot, runningImages, imageId) {
+  const record = runningImages[imageId];
   let projectionError;
-  // An image opened without MCP has no projection to stop, and no route to
+  // An image started without MCP has no projection to stop, and no route to
   // ask over either.
-  if (open.projectionPort !== undefined) {
+  if (record.projectionPort !== undefined) {
     try {
-      await callImageTool(projectRoot, open, "image_evaluate", {
-        code: pifsStopCode(open.projectionPort),
+      await callImageTool(projectRoot, record, "image_evaluate", {
+        code: pifsStopCode(record.projectionPort),
       });
     } catch (error) {
       projectionError = error;
     }
   }
-  const closed = await runLifecycle(
+  const stopped = await runLifecycle(
     () => stopProjectImage({ projectRoot, imageId }),
-    `PLexus could not close image ${imageId}.`,
+    `PLexus could not stop image ${imageId}.`,
   );
-  return { stoppedImages: closed.stoppedImages.map((image) => image.id), projectionError };
+  return { stoppedImage: stopped.stoppedImage?.id, projectionError };
 }
 
-export async function closeAgentImage(projectRoot, imageId) {
-  const openImages = readOpenImages(projectRoot);
-  const identifiers = imageId === undefined
-    ? Object.keys(openImages)
+/**
+ * Stop one image, or with `all`, every image this project started. Naming no
+ * image stops the default one, as every other command addresses it; `all` is
+ * the cleanup, and says so where the caller can see it.
+ *
+ * @param {string} projectRoot
+ * @param {string} [imageId]
+ * @param {{ all?: boolean }} [options]
+ */
+export async function stopAgentImage(projectRoot, imageId, options = {}) {
+  const runningImages = readRunningImages(projectRoot);
+  if (options.all && imageId !== undefined) {
+    throw new Error("Stopping every image takes no image id.");
+  }
+  const identifiers = options.all
+    ? Object.keys(runningImages)
     : [resolveImageId(projectRoot, imageId)];
   if (identifiers.length === 0) {
-    throw new Error("No open pharo-agent image.");
+    throw new Error("No pharo-agent image is running.");
   }
   for (const identifier of identifiers) {
-    if (!openImages[identifier]) {
-      throw new Error(`Image ${identifier} is not open.`);
+    if (!runningImages[identifier]) {
+      throw new Error(`Image ${identifier} is not running.`);
     }
   }
 
   const stoppedImages = [];
   const projectionErrors = [];
-  const remaining = { ...openImages };
+  const remaining = { ...runningImages };
   for (const identifier of identifiers) {
-    const closed = await closeOneImage(projectRoot, openImages, identifier);
+    const stopped = await stopOneImage(projectRoot, runningImages, identifier);
     delete remaining[identifier];
-    writeOpenImages(projectRoot, remaining);
-    stoppedImages.push(...closed.stoppedImages);
-    if (closed.projectionError) {
-      projectionErrors.push(`${identifier}: ${closed.projectionError.message}`);
+    writeRunningImages(projectRoot, remaining);
+    if (stopped.stoppedImage) {
+      stoppedImages.push(stopped.stoppedImage);
+    }
+    if (stopped.projectionError) {
+      projectionErrors.push(`${identifier}: ${stopped.projectionError.message}`);
     }
   }
   if (projectionErrors.length > 0) {
-    throw new Error(`Images closed, but PIFS cleanup failed: ${projectionErrors.join("; ")}`);
+    throw new Error(`Images stopped, but PIFS cleanup failed: ${projectionErrors.join("; ")}`);
   }
   return { stoppedImages };
 }
 
-export function agentImageStatus(projectRoot) {
-  const openImages = readOpenImages(projectRoot);
-  let defaultImage;
-  try {
-    defaultImage = defaultImageId(projectRoot);
-  } catch {
-    defaultImage = undefined;
-  }
-  return {
-    ...(defaultImage ? { defaultImage } : {}),
-    images: Object.values(openImages).map((open) => ({
-      ...open,
-      isDefault: open.imageId === defaultImage,
-    })),
-  };
-}
-
 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

package/src/mcpServer.js

@@ -0,0 +1,153 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  callImageTool,
+  listImageTools,
+  toolResult,
+  version,
+  withImageSelector,
+} from "./gateway.js";
+import { listImages } from "./images.js";
+import { startAgentImage, stopAgentImage } from "./live.js";
+import { readRunningImage } from "./runtime.js";
+
+// The host loads only tool names and these instructions at session start and
+// defers the rest, so this is what decides whether Pharo tools are searched
+// for at all. It is the conditional guidance the generated guide gives,
+// written where the host can act on it.
+export const serverInstructions = `Live Pharo images for this project: reading and writing Smalltalk code in the
+image, running tests, finding senders and implementors, applying critiques,
+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.
+
+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 = [
+  {
+    name: "image_start",
+    description:
+      "Start one of this project's Pharo images, creating it from its template "
+      + "when it does not exist yet, and mount its source projection. The "
+      + "image's own tools are listed once it answers.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        image: {
+          type: "string",
+          description: "Image id to start. Defaults to the project's default image.",
+        },
+      },
+    },
+  },
+  {
+    name: "image_list",
+    description:
+      "List this project's declared images, which are running, and the route "
+      + "and mount of each running one.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "image_stop",
+    description:
+      "Stop a running image and the source projection this project started for it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        image: {
+          type: "string",
+          description: "Image id to stop. Defaults to the project's default image.",
+        },
+        all: {
+          type: "boolean",
+          description: "Stop every image this project started, instead of one.",
+        },
+      },
+    },
+  },
+];
+
+// Resolved per request rather than once at startup. A host starts this server
+// when its session starts, which is before anyone has started an image, so
+// resolving then meant the server died on its first line.
+async function runningImageTools(projectRoot, defaultImage) {
+  let running;
+  try {
+    running = readRunningImage(projectRoot, defaultImage);
+  } catch {
+    // No image running, none configured, or one running without MCP. The image
+    // 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));
+}
+
+export async function serveImagesMcp(resolveProjectRoot, defaultImage) {
+  const server = new Server(
+    { name: "pharo-agent", version },
+    { capabilities: { tools: { listChanged: true } }, instructions: serverInstructions },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    let projectRoot;
+    try {
+      projectRoot = resolveProjectRoot();
+    } 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: [...lifecycleTools, ...(await runningImageTools(projectRoot, defaultImage))],
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { image, all, ...argumentsValue } = request.params.arguments ?? {};
+    const selected = image ?? 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
+    // server, and an image that happened to hold one must not decide what
+    // starting an image means.
+    if (request.params.name === "image_start") {
+      const started = await startAgentImage(projectRoot, selected);
+      await server.sendToolListChanged();
+      return toolResult({ ok: true, ...started });
+    }
+    if (request.params.name === "image_list") {
+      return toolResult({ ok: true, ...listImages(projectRoot) });
+    }
+    if (request.params.name === "image_stop") {
+      const stopped = all
+        ? await stopAgentImage(projectRoot, undefined, { all: true })
+        : await stopAgentImage(projectRoot, selected);
+      await server.sendToolListChanged();
+      return toolResult({ ok: true, ...stopped });
+    }
+
+    // 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 running = readRunningImage(projectRoot, selected);
+    return toolResult(
+      await callImageTool(projectRoot, running, request.params.name, argumentsValue),
+    );
+  });
+
+  await server.connect(new StdioServerTransport());
+}

package/src/project.js

@@ -3,7 +3,7 @@ import path from "node:path";
 
 export const projectConfigFileName = "plexus.json";
 
-export function findProjectRoot(start = process.cwd()) {
+function projectRootAbove(start) {
   let directory = path.resolve(start);
 
   while (true) {
@@ -13,12 +13,28 @@ export function findProjectRoot(start = process.cwd()) {
 
     const parent = path.dirname(directory);
     if (parent === directory) {
-      throw new Error("No plexus.json found above the current directory");
+      return undefined;
     }
     directory = parent;
   }
 }
 
+export function findProjectRoot(start = process.cwd()) {
+  const found = projectRootAbove(start);
+  if (found) return found;
+
+  // A plugin's MCP server is started by the host, in the plugin's own
+  // directory rather than the project's, so the working directory leads
+  // nowhere. The host says where the project is, and that is only consulted
+  // here, after the ordinary search has failed, so running the CLI inside a
+  // project still answers with that project.
+  const hosted = process.env.CLAUDE_PROJECT_DIR;
+  const hostedRoot = hosted ? projectRootAbove(hosted) : undefined;
+  if (hostedRoot) return hostedRoot;
+
+  throw new Error("No plexus.json found above the current directory");
+}
+
 export function enclosingProjectRoot(start) {
   const directory = path.resolve(start);
   const parent = path.dirname(directory);

package/src/runtime.js

@@ -6,8 +6,8 @@ export function runtimeDirectory(projectRoot) {
   return path.join(pluginDirectory(projectRoot), "runtime");
 }
 
-export function activePath(projectRoot) {
-  return path.join(runtimeDirectory(projectRoot), "active.json");
+export function runningImagesPath(projectRoot) {
+  return path.join(runtimeDirectory(projectRoot), "running.json");
 }
 
 export function readJson(filePath) {
@@ -30,23 +30,22 @@ export function writeConfig(projectRoot, config) {
   fs.writeFileSync(configPath(projectRoot), `${JSON.stringify(config, null, 2)}\n`);
 }
 
-export function readOpenImages(projectRoot) {
-  const filePath = activePath(projectRoot);
+export function readRunningImages(projectRoot) {
+  const filePath = runningImagesPath(projectRoot);
   if (!fs.existsSync(filePath)) return {};
   const recorded = readJson(filePath);
-  if (recorded && typeof recorded.images === "object" && recorded.images !== null) {
-    return recorded.images;
-  }
-  return typeof recorded?.imageId === "string" ? { [recorded.imageId]: recorded } : {};
+  return recorded && typeof recorded.images === "object" && recorded.images !== null
+    ? recorded.images
+    : {};
 }
 
-export function writeOpenImages(projectRoot, images) {
+export function writeRunningImages(projectRoot, images) {
   if (Object.keys(images).length === 0) {
-    fs.rmSync(activePath(projectRoot), { force: true });
+    fs.rmSync(runningImagesPath(projectRoot), { force: true });
     return;
   }
   fs.mkdirSync(runtimeDirectory(projectRoot), { recursive: true });
-  fs.writeFileSync(activePath(projectRoot), `${JSON.stringify({ images }, null, 2)}\n`);
+  fs.writeFileSync(runningImagesPath(projectRoot), `${JSON.stringify({ images }, null, 2)}\n`);
 }
 
 export function defaultImageId(projectRoot) {
@@ -70,7 +69,7 @@ export function defaultImageId(projectRoot) {
   }
   throw new Error(
     `Several images are configured (${images.map((image) => image.id).join(", ")}); `
-      + "choose one with pharo-agent image use <id>, or pass --image <id>.",
+      + "choose one with pharo-agent image use <id>, or name one.",
   );
 }
 
@@ -82,26 +81,26 @@ export function resolveImageId(projectRoot, imageId) {
   return imageId;
 }
 
-export function readOpenImage(projectRoot, imageId) {
+export function readRunningImage(projectRoot, imageId) {
   const resolved = resolveImageId(projectRoot, imageId);
-  const open = readOpenImages(projectRoot)[resolved];
-  if (!open) {
+  const running = readRunningImages(projectRoot)[resolved];
+  if (!running) {
     throw new Error(
-      `Image ${resolved} is not open. Run pharo-agent open${imageId ? ` --image ${resolved}` : ""} first.`,
+      `Image ${resolved} is not running. Run pharo-agent image start ${resolved} first.`,
     );
   }
-  if (open.mcp === false) {
+  if (running.mcp === false) {
     throw new Error(
-      `Image ${resolved} is open without MCP, so it offers no Pharo tools. `
+      `Image ${resolved} is running without MCP, so it offers no Pharo tools. `
         + "Register an image on a Pharo version the MCP contract supports to use them.",
     );
   }
-  return open;
+  return running;
 }
 
-// A record in the project's runtime state says this project opened the image,
+// A record in the project's runtime state says this project started 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
+// relaunches on the next start, 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;
@@ -114,14 +113,14 @@ export function imageProcessIsAlive(pid) {
   }
 }
 
-export function openedImageIsAlive(open) {
+export function recordedImageIsRunning(record) {
   let state;
   try {
-    state = readJson(open.statePath);
+    state = readJson(record.statePath);
   } catch {
     return false;
   }
-  const image = (state.images ?? []).find((candidate) => candidate.id === open.imageId);
+  const image = (state.images ?? []).find((candidate) => candidate.id === record.imageId);
   return image?.status === "running" && imageProcessIsAlive(image.pid);
 }
 
@@ -164,7 +163,7 @@ export function selectRunningImage(state, imageId) {
 // 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`
+  return `Image ${image.id} started 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.";
 }