@evref-bl/pharo-agent 0.10.2 → 0.12.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pharo-agent",
   "displayName": "Pharo Agent",
-  "version": "0.10.2",
+  "version": "0.12.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
@@ -35,8 +35,10 @@ the file ownership rules and [Images](docs/images.md) for image-side MCP updates
 
 Node 22.12 or later.
 
-The source projection currently supports macOS and needs
-[fuse-t](https://www.fuse-t.org/). Its daemon is downloaded for you.
+Images and their Pharo tools run anywhere Node does. The source projection is
+the exception: it needs macOS with [fuse-t](https://www.fuse-t.org/), whose
+daemon is downloaded for you. Everywhere else an image starts with its tools
+and says that the projection is not available, rather than failing.
 
 ## What the agent gets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evref-bl/pharo-agent",
-  "version": "0.10.2",
+  "version": "0.12.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.12.1",
     "@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.2",
+  "version": "0.12.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.2 init --host claude
+npx --yes @evref-bl/pharo-agent@0.12.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;
@@ -33,11 +29,18 @@ function parseInit(args) {
   return { host, mountRoot };
 }
 
+/**
+ * The template is required, and the loop below refuses the call without one,
+ * which the dynamic key assignment hides from the typechecker.
+ *
+ * @returns {{ id: string, template: string, category?: string, profile?: string }}
+ */
 function parseImageAdd(args) {
   const [id, ...rest] = args;
   if (!id || id.startsWith("--")) {
     throw new Error("image add requires an image id");
   }
+  /** @type {{ id: string, template?: string, category?: string, profile?: string }} */
   const parsed = { id };
   const options = {
     "--template": "template",
@@ -60,7 +63,22 @@ function parseImageAdd(args) {
   if (!parsed.template) {
     throw new Error("image add requires --template <name>");
   }
-  return parsed;
+  return { ...parsed, template: parsed.template };
+}
+
+// `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) {
@@ -115,6 +133,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 +164,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 +194,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 +210,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 { loadProjectState } from "@evref-bl/plexus";
 import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-import {
-  readJson,
-  readOpenImage,
   selectRunningImage,
   unappliedPharoMcpPin,
 } from "./runtime.js";
@@ -20,15 +13,18 @@ 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 = loadProjectState(running.statePath);
+  if (!state) {
+    throw new Error(`PLexus has no state at ${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 +45,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 +60,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 +85,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,53 @@ 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 Pharo tools. Omit the id to use the\n"
+      + "project's default image. Images already running stay running. A source projection is\n"
+      + "mounted on macOS with fuse-t; elsewhere the image starts without one and says so.\n"
+      + "Pharo versions outside the MCP support range start without tools or a 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 any source projection it has, or the project's default\n"
+      + "image when 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

@@ -1,77 +1,78 @@
-import {
-  configuredImages,
-  projectIdentity,
-  readProjectConfig,
-  writeProjectConfig,
-} from "./project.js";
-import { readConfig, readOpenImages, writeConfig } from "./runtime.js";
+import { declareProjectImage, removeProjectImage } from "@evref-bl/plexus";
+import { configuredImages } from "./project.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}.`,
+    );
   }
 }
 
-function derivedImageName(projectRoot, imageId) {
-  const { name } = projectIdentity(projectRoot);
-  return `${name}-{workspaceId}-${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,
+      };
+    }),
   };
 }
 
-/** @param {{ id: string, template?: string, category?: string, profile?: string }} request */
+/**
+ * PLexus owns `plexus.json`, so PLexus writes it. This package chooses what
+ * to declare — the load script that puts the pinned MCP in the image — and
+ * leaves the schema, the name template, the defaults and the validation to
+ * the package that reads them back.
+ *
+ * @param {{ id: string, template: string, category?: string, profile?: string }} request
+ */
 export function addImage(projectRoot, request) {
   const { id, template, category, profile } = request;
-  const config = readProjectConfig(projectRoot);
-  const images = Array.isArray(config.images) ? config.images : [];
-  if (images.some((image) => image.id === id)) {
-    throw new Error(`Image ${id} is already configured.`);
-  }
-  const imageName = derivedImageName(projectRoot, id);
-  if (images.some((image) => image.imageName === imageName)) {
-    throw new Error(`Image name ${imageName} is already configured.`);
+  const declaredBefore = configuredImages(projectRoot).length;
+  const config = declareProjectImage(projectRoot, {
+    id,
+    templateName: template,
+    ...(category ? { templateCategory: category } : {}),
+    ...(profile ? { profileId: profile } : {}),
+    loadScript: defaultLoadScript,
+  });
+  const declared = config.images.find((image) => image.id === id);
+  if (!declared) {
+    throw new Error(`PLexus declared image ${id} but did not record it.`);
   }
 
-  const image = {
-    id,
-    imageName,
-    active: true,
-    mcp: { loadScript: defaultLoadScript, loadPolicy: "ifMissing" },
-    create: {
-      kind: "template",
-      ...(profile ? { profileId: profile } : {}),
-      templateName: template,
-      ...(category ? { templateCategory: category } : {}),
-      cleanupPolicy: "workspace_cleanup_only",
-    },
-  };
-  writeProjectConfig(projectRoot, { ...config, images: [...images, image] });
   const pluginConfig = readConfig(projectRoot);
-  const isDefault = pluginConfig.defaultImage === undefined && images.length === 0;
+  const isDefault = pluginConfig.defaultImage === undefined && declaredBefore === 0;
   if (isDefault) {
     writeConfig(projectRoot, { ...pluginConfig, defaultImage: id });
   }
   return {
     id,
-    imageName,
+    imageName: declared.imageName,
     isDefault,
     templateName: template,
     ...(category ? { templateCategory: category } : {}),
@@ -87,16 +88,11 @@ export function useImage(projectRoot, id) {
 }
 
 export function removeImage(projectRoot, id) {
-  const config = readProjectConfig(projectRoot);
-  const images = Array.isArray(config.images) ? config.images : [];
-  if (!images.some((image) => image.id === id)) {
+  if (!configuredImages(projectRoot).some((image) => image.id === id)) {
     throw new Error(`Image ${id} is not configured.`);
   }
-  assertNoOpenImage(projectRoot, id, "removing it");
-  writeProjectConfig(projectRoot, {
-    ...config,
-    images: images.filter((image) => image.id !== id),
-  });
+  assertNotRunning(projectRoot, id, "removing it");
+  removeProjectImage(projectRoot, id);
   const pluginConfig = readConfig(projectRoot);
   if (pluginConfig.defaultImage === id) {
     const { defaultImage: _removed, ...rest } = pluginConfig;